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Introduction 



Advanced Swift Is quite a bold title for a book, so perhaps we should start with what we 
mean by it. 

When we began writing the first edition of this book. Swift was barely a year old. We did 
so before the beta of 2.0 was released — albeit tentatively, because we suspected the 
language would continue to evolve as it entered its second year. Few languages — 
perhaps no other language — have been adopted so rapidly by so many developers. 

But that left people with unanswered questions. How do you write “idiomatic” Swift? Is 
there a correct way to do certain things? The standard library provided some clues, but 
even that has changed over time, dropping some conventions and adopting others. Over 
the past three years. Swift has evolved at a high pace, and it has become clearer what 
idiomatic Swift is. 

To someone coming from another language. Swift can resemble everything you like 
about your language of choice. Low-level bit twiddling can look very similar to (and can 
be as performant as) C, but without many of the undefined behavior gotchas. The 
lightweight trailing closure syntax of map or filter will be familiar to Rubyists. Swift 
generics are similar to C++ templates, but with type constraints to ensure generic 
functions are correct at the time of definition rather than at the time of use. The 
flexibility of higher-order functions and operator overloading means you can write code 
that’s similar in style to Haskell or F#. And the @objc and dynamic keywords allow you 
to use selectors and runtime dynamism in ways you would in Objectlve-C. 

Given these resemblances, it’s tempting to adopt the Idioms of other languages. Case in 
point: Objective-C example projects can almost be mechanically ported to Swift. The 
same is true for Java or C# design patterns. And monad tutorials appeared to be 
everyone’s favorite blog post topic in the first few months after Swift’s introduction. 

But then comes the frustration. Why can’t we use protocol extensions with associated 
types like interfaces in Java? Why are arrays not covariant in the way we expect? Why 
can’t we write “functor?” Sometimes the answer is because the part of Swift in question 
isn’t yet implemented. But more often, it’s either because there’s a different Swift-like 
way to do what you want to do, or because the Swift feature you thought was like the 
equivalent in some other language is not quite what you think. 

Swift is a complex language — most programming languages are. But it hides that 
complexity well. You can get up and running developing apps in Swift without needing 
to know about generics or overloading or the difference between static and dynamic 
dispatch. You may never need to call into a C library or write your own collection type, 
but after a while, we think you’ll find it necessary to know about these things — either to 



improve your code’s performance, to make it more elegant or expressive, or just to get 
certain things done. 

Learning more about these features is what this book is about. We intend to answer 
many of the “How do I do this?” or “Why does Swift behave like that?” questions we’ve 
seen come up on various forums. Hopefully, once you’ve read our book, you’ll have gone 
from being aware of the basics of the language to knowing about many advanced 
features and having a much better understanding of how Swift works. Being familiar 
with the material presented is probably necessary, if not sufficient, for calling yourself 
an advanced Swift programmer. 


Who Is This Book For? 


This book targets experienced (though not necessarily expert) programmers — such as 
existing Apple-platform developers, or those coming from other languages such as Java 
or C++ — who want to bring their knowledge of Swift to the same level as that of 
Objective-C or some other language. It’s also suitable for new programmers who started 
on Swift, have grown familiar with the basics, and are looking to take things to the next 
level. 

The book isn’t meant to be an introduction to Swift; it assumes you’re familiar with the 
syntax and structure of the language. If you want some good, compact coverage of the 
basics of Swift, the best source is the official Apple Swift book (available on iBooks or on 
Apple’s website ). If you’re already a conhdent programmer, you could try reading our 
book and the Apple Swift book in parallel. 

This is also not a book about programming for macOS or iOS devices. Of course, since 
Swift is currently mainly used on Apple platforms, we’ve tried to include examples of 
practical use, but we hope this book will be useful for non-Apple-platform programmers 
as well. The vast majority of the examples in the book should run unchanged on other 
operating systems. The ones that don’t are either fundamentally tied to Apple’s 
platforms (because they use iOS frameworks or rely on the Objective-C runtime) or only 
require minimal changes, such as replacing the BSD-specihc function we use to generate 
random numbers with a Linux equivalent. 




Themes 


We’ve organized the book under the heading of basic concepts. There are in-depth 
chapters on some fundamentai basic concepts iike optionals or strings, and some deeper 
dives into topics iike C interoperability. But throughout the book, hopefully a few 
themes regarding Swift emerge: 

Swift is both a high- and iow-level language. Swift allows you to write code similarly 
to Ruby and Python, with map and reduce, and to write your own higher-order functions 
easily. Swift also allows you to write fast code that compiles directly to native binaries 
with performance similar to code written in C. 

What’s exciting to us, and what’s possibly the aspect of Swift we most admire, is that 
you’re able to do both these things at the same time. Mapping a closure expression over 
an array compiles to the same assembly code as looping over a contiguous block of 
memory does. 

However, there are some things you need to know about to make the most of this feature. 
For example, it will benefit you to have a strong grasp on how structs and classes differ, 
or an understanding of the difference between dynamic and static method dispatch. 
We’ll cover topics such as these in more depth later on. 

Swift is a multi-paradigm language. You can use it to write object-oriented code or 
pure functional code using Immutable values, or you can write imperative C-like code 
using pointer arithmetic. 

This is both a blessing and a curse. It’s great, in that you have a lot of tools available to 
you, and you aren’t forced into writing code one way. But it also exposes you to the risk 
of writing Java or C or Objective-C in Swift. 

Swift still has access to most of the capabilities of Objective-C, including message 
sending, runtime type Identification, and key-value observation. But Swift introduces 
many capabilities not available in Objective-C. 


Erik Meijer, a well-known programming language expert, tweeted the following in 
October 2015: 




At this point, ©SwiftLang is probabiy a better, and more vaiuabie, vehicie for 
iearning functionai programming than Haskeii. 


Swift is a good introduction to a more functionai styie through its use of generics, 
protocois, vaiue types, and ciosures. It’s even possible to write operators that compose 
functions together. The early months of Swift brought many functional programming 
blog posts into the world. But since the release of Swift 2.0 and the introduction of 
protocol extensions, this trend has shifted. 

Swift is very flexible. In the introduction to the book On Lisp, Paul Graham writes that: 


Experienced Lisp programmers divide up their programs differently. As well as 
top-down design, they follow a principle which could be called bottom-up 
design- changing the language to suit the problem. In Lisp, you don’t just 
write your program down toward the language, you also build the language up 
toward your program. As you’re writing a program you may think “I wish Lisp 
had such-and-such an operator.” So you go and write it. Afterward you realize 
that using the new operator would simplify the design of another part of the 
program, and so on. Language and program evolve together. 


Swift is a long way from Lisp. But still, we feel like Swift shares this characteristic of 
encouraging “bottom-up” programming — of making it easy to write very general 
reusable building blocks that you then combine into larger features, which you then use 
to solve your actual problem. Swift is particularly good at making these building blocks 
feel like primitives — like part of the language. A good demonstration of this is that the 
many features you might think of as fundamental building blocks, like optionals or basic 
operators, are actually defined in a library — the Swift standard library — rather than 
directly in the language. Trailing closures enable you to extend the language with 
features that feel like they’re built in. 

Swift code can be compact and concise while still being clear. Swift lends itself to 
relatively terse code. There’s an underlying goal here, and it isn’t to save on typing. The 
idea is to get to the point quicker and to make code readable by dropping a lot of the 
“ceremonial” boilerplate you often see in other languages that obscure rather than 
clarify the meaning of the code. 

For example, type inference removes the clutter of type declarations that are obvious 
from the context. Semicolons and parentheses that add little or no value are gone. 




Generics and protocol extensions encourage you to avoid repeating yourself by 
packaging common operations into reusable functions. The goal is to write code that’s 
readable at a glance. 

At first, this can be off-putting. If you’ve never used functions like map, filter, and reduce 
before, they might look harder to read than a simple for loop. But our hope is that this is 
a short learning curve and that the reward is code that is more “obviously correct’’ at first 
glance. 

Swift tries to be as safe as is practieal, until you tell it not to be. This is unlike 
languages such as C and C++ (where you can be unsafe easily just by forgetting to do 
something), or like Haskell or Java (which are sometimes safe whether or not you like it). 

Eric Lippert, one of the principal designers of C#, wrote about his 10 regrets of C#, 
including the lesson that: 


sometimes you need to implement features that are only for experts who 
are building infrastructure; those features should be clearly marked as 
dangerous—not invitingly similar to features from other languages. 


Eric was specifically referring to C#’s finalizers, which are similar to C++ destructors. But 
unlike destructors, they run at a nondeterministic time (perhaps never) at the behest of 
the garbage collector (and on the garbage collector’s thread). However, Swift, being 
reference counted, does execute a class’s deinit deterministically. 

Swift embodies this sentiment in other ways. Undefined and unsafe behavior is avoided 
by default. For example, a variable can’t be used until it’s been initialized, and using 
out-of-bounds subscripts on an array will trap, as opposed to continuing with possibly 
garbage values. 

There are a number of “unsafe” options available (such as the unsafeBitcast function, or 
the UnsafeMutablePointer type) for when you really need them. But with great power 
comes great undefined behavior. You can write the following: 

var someArray = [1,2,3] 

let uhOh = someArray.withUnsafeBufferPointer { ptr in 
// ptr is only valid within this block, but 
//there is nothing stopping you letting it 
//escape into the wild: 




return ptr 


} 

//Later... 

print(uh0h[10]) 

It’ll compile, but who knows what it’ll do. However, you can’t say nobody warned you. 

Swift is an opinionated language. We as authors have strong opinions about the 
“right” way to write Swift. You’ll see many of them in this book, sometimes expressed as 
if they’re facts. But they’re just, like, our opinions, man. Feel free to disagree! Swift is 
still a young language, and many things aren’t settled. What’s more is that many blog 
posts are flat-out wrong or outdated (including several ones we wrote, especially in the 
early days). Whatever you’re reading, the most important thing is to try things out for 
yourself, check how they behave, and decide how you feel about them. Think critically, 
and beware of out-of-date information. 

Swift continues to evolve. The period of major yearly syntax changes may be behind 
us, but important areas of the language are still new (strings), in flux (the generics 
system), or haven’t been tackled yet (concurrency). 


Terminology 

‘When I use a word,’ Humpty Dumpty said, in rather a scornful tone, ‘it means 
just what I choose it to mean — neither more nor less.’ 

— Through the Looking Glass, by Lewis Carroll 


Programmers throw around terms of art a lot. To avoid confusion, what follows are some 
definitions of terms we use throughout this book. Where possible, we’re trying to adhere 
to the same usage as the official documentation, or sometimes a definition that’s been 
widely adopted by the Swift community. Many of these definitions are covered in more 
detail in later chapters, so don’t worry if not everything makes sense on first reading. If 
you’re already familiar with all of these terms, it’s still best to skim through to make sure 
your accepted meanings don’t differ from ours. 

In Swift, we make the distinctions between values, variables, references, and constants. 




A value is immutable and forever — it never changes. For example, 1 , true, and [1,2,3] 
are all values. These are examples of literals, but values can also be generated at 
runtime. The number you get when you square the number five is a value. 

When we assign a value to a name using var x = [1,2], we’re creating a variable named x 
that holds the value [1,2]. By changing x, e.g. hy performing x.append(3), we didn’t 
change the original value. Rather, we replaced the value that x holds with the new value, 
[1,2,3] — at least logically, if not in the actual implementation (which might actually just 
tack a new entry on the back of some existing memory). We refer to this as mutating the 
variable. 

We can declare constant variables (constants, for short) with let instead of var. Once a 
constant has been assigned a value, it can never be assigned a new value. 

We also don’t need to give a variable a value immediately. We can declare the variable 
first (let x: Int) and then later assign a value to it (x = 1 ). Swift, with its emphasis on 
safety, will check that all possible code paths lead to a variable being assigned a value 
before its value can be read. There’s no concept of a variable having an as-yet-undeflned 
value. Of course, if the variable was declared with let, it can only be assigned to once. 

Structs and enums are value types. When you assign one struct variable to another, the 
two variables will then contain the same value. You can think of the contents as being 
copied, but it’s more accurate to say that one variable was changed to contain the same 
value as the other. 

A reference is a special kind of value: a value that "points to” another value. Because 
two references can refer to the same value, this Introduces the possibility of that value 
getting mutated by two different parts of the program at once. 

Classes are reference types. You can’t hold an instance of a class (which we might 
occasionally call an object — a term fraught with troublesome overloading!) directly in 
a variable. Instead, you must hold a reference to it in a variable and access it via that 
reference. 

Reference types have identity — you can check if two variables are referring to the exact 
same object by using ===. You can also check if they’re equal, assuming == is 
implemented for the relevant type. Two objects with different identity can still be equal. 

Value types don’t have identity. You can’t check if a particular variable holds the “same” 
number 2 as another. You can only check if they both contain the value 2. = = = is really 
asking: “Do both these variables hold the same reference as their value?” In 



programming language literature, = = is sometimes called structural equality, and = = = 
is called pointer equality or reference equality. 

Class references aren’t the only kind of reference in Swift. For example, there are also 
pointers, accessed through withUnsafeMutablePointer functions and the like. But 
classes are the simplest reference type to use, in part because their reference-like nature 
is partially hidden from you by syntactic sugar. You don’t need to do any explicit 
“dereferencing” like you do with pointers in some other languages. (We’ll cover the other 
kind of references in more detail in the chapter on interoperability.) 

A variable that holds a reference can be declared with let — that is, the reference is 
constant. This means that the variable can never be changed to refer to something else. 
But — and this is important — it doesn’t mean that the object it refers to can’t be changed. 
So when referring to a variable as a constant, be careful — it’s only constant in what it 
points to. It doesn’t mean what it points to is constant. (Note: if those last few sentences 
sound like doublespeak, don’t worry, as we cover this again in the chapter on structs and 
classes). Unfortunately, this means that when looking at a declaration of a variable with 
let, you can’t tell at a glance whether or not what’s being declared is completely 
immutable. Instead, you have to know whether it’s holding a value type or a reference 
type. 

We refer to types as having value semantics to distinguish a value type that performs a 
deep copy. This copy can occur eagerly (whenever a new variable is introduced) or lazily 
(whenever a variable gets mutated). 

Here we hit another complication. If our struct contains reference types, the reference 
types won’t automatically get copied upon assigning the struct to a new variable. 

Instead, the references themselves get copied. This is called a shadow copy. 

For example, the Data struct in Foundation is a wrapper around the NSData reference 
type. However, the authors of the Data struct took extra steps to also perform a deep 
copy of the NSData object whenever the Data struct is mutated. They do this efficiently 
using a technique called copy-on-write, which we’ll explain in the chapter on structs and 
classes. For now, it’s important to know that this behavior doesn’t come for free. 

The collections in Swift are also wrapping reference types and use copy-on-write to 
efficiently provide value semantics. However, if the elements in a collection are 
references (for example, an array containing objects), the objects won’t get copied. 
Instead, only the references get copied. This means that a Swift array only has value 
semantics if its elements have value semantics too. 



Some classes are completely Immutable — that is, they provide no methods for changing 
their internal state after they’re created. This means that even though they’re classes, 
they also have value semantics (because even if they’re shared, they can never change). 
Be careful though — only final classes can be guaranteed not to be subclassed with 
added mutable state. 

In Swift, functions are also values. You can assign a function to a variable, have an array 
of functions, and call the function held in a variable. Functions that take other functions 
as arguments (such as map, which takes a function to transform every element of a 
sequence) or return functions are referred to as higher-order funetions. 

Functions don’t have to be declared at the top level — you can declare a function within 
another function or in a do or other scope. Functions defined within an outer scope, but 
passed out from it (say, as the returned value of a function), can “capture” local variables, 
in which case those local variables aren’t destroyed when the local scope ends, and the 
function can hold state through them. This behavior is called “closing over” variables, 
and functions that do this are called closures. 

Functions can be declared either with the func keyword or by using a shorthand {} 
syntax called a closure expression. Sometimes this gets shortened to “closures,” but 
don’t let it give you the impression that only closure expressions can be closures. 
Functions declared with the func keyword are also closures when they close over 
external variables. 

Functions are held by reference. This means assigning a function that has captured state 
to another variable doesn’t copy that state; it shares it, similar to object references. 
What’s more is that when two closures close over the same local variable, they both share 
that variable, so they share state. This can be quite surprising, and we’ll discuss this 
more in the chapter on functions. 

Functions defined inside a class or protocol are methods, and they have an implicit self 
parameter. Sometimes we call functions that aren’t methods free functions. This Is to 
distinguish them from methods. 

A fully qualified function name in Swift includes not just the function’s base name (the 
part before the parentheses), but also the argument labels. For example, the full name of 
the method for moving a collection index by a number of steps is index(_:offsetBy:), 
indicating that this function takes two arguments (represented by the two colons), the 
first one of which has no label (represented by the underscore). We often omit the labels 
in the book if it’s clear from the context what function we’re referring to (the compiler 
allows you to do the same). 



Free functions, and methods called on structs, are statically dispatched. This means 
the function that’ll be called is known at compile time. It also means the compiler might 
be able to inline the function, i.e. not call the function at all, but instead replace it with 
the code the function would execute. The optimizer can also discard or simplify code 
that it can prove at compile time won’t actually run. 

Methods on classes or protocols might be dynamically dispatched. This means the 
compiler doesn’t necessarily know at compile time which function will run. This 
dynamic behavior is done either by using vtables (similar to how Java or C++ dynamic 
dispatch work), or in the case of some @objc classes and protocols, by using selectors 
and objc_msgSend. 

Subtyping and method overriding is one way of getting polymorphic behavior, 
i.e. behavior that varies depending on the types involved. A second way is function 
overloading, where a function is written multiple times for different types. (It’s 
important not to mix up overriding and overloading, as they behave very differently.) A 
third way is via generics, where a function or method is written once to take any type 
that provides certain functions or methods, but the implementations of those functions 
can vary. Unlike method overriding, the results of function overloading and generics are 
known statically at compile time. We’ll cover this more in the generics chapter. 


Swift Style Guide 

When writing this book, and when writing Swift code for our own projects, we try to stick 
to the following rules: 

-> For naming, clarity at the point of use is the most Important consideration. Since 
APIs are used many more times than they’re declared, their names should be 
optimized for how well they work at the call site. Familiarize yourself with the 
Swift API Design Guidelines and try to adhere to them in your own code. 

-> Clarity is often helped by conciseness, but brevity should never be a goal in and of 
itself. 

-> Always add documentation comments to functions — especially generic ones. 

-> Types start with UpperCaseLetters. Functions, variables, and enum cases start 
with lowerCaseLetters. 

-> Use type inference. Explicit but obvious types get in the way of readability. 




-> Don’t use type inference in cases of ambiguity or when defining contracts (which 
is why, for exampie, funcs have an expiicit return type). 

-> Defauit to structs uniess you actuaiiy need a ciass-oniy feature or reference 
semantics. 

-> Mark ciasses as final uniess you’ve expiicitly designed them to be inheritable. If 
you want to use inheritance internally but not allow subclassing for external 
clients, mark a class public but not open. 

-> Use the trailing closure syntax, except when that closure is immediately followed 
by another opening brace. 

-> Use guard to exit functions early. 

-> Eschew force-unwraps and implicitly unwrapped optionals. They’re occasionally 
useful, but needing them constantly is usually a sign something is wrong. 

-> Don’t repeat yourself. If you find you’ve written a very similar piece of code more 
than a couple of times, extract it into a function. Consider making that function a 
protocol extension. 

-> Favor map and filter. But don’t force it: use a for loop when it makes sense. The 
purpose of higher-order functions is to make code more readable. An obfuscated 
use of reduce when a simple for loop would he clearer defeats this purpose. 

-> Favor Immutable variables: default to let unless you know you need mutation. 
But use mutation when it makes the code clearer or more efficient. Again, don’t 
force it: a mutating method on a struct is often more idiomatic and efficient than 
returning a brand new struct. 

-> Swift generics tend to lead to very long function signatures. Unfortunately, we 
have yet to settle on a good way of breaking up long function declarations into 
multiple lines. We’ll try to be consistent in how we do this in sample code. 

-> Leave off self, when you don’t need it. In closure expressions, it’s a clear signal 
that self is being captured by the closure. 

-> Write extensions on existing types and protocols, instead of free functions, 
whenever you can. This helps readability and discoverability. 

One final note about our code samples throughout the book: to save space and focus on 
the essentials, we usually omit import statements that would be required to make the 
code compile. If you try out the code yourself and the compiler tells you it doesn’t 
recognize a particular symbol, try adding an import Foundation or import UIKit 
statement. 



Built-In 

Collections 




Collections of elements are among the most important data types in any programming 
language. Good language support for different kinds of containers has a big impact on 
programmer productivity and happiness. Swift places special emphasis on sequences 
and collections — so much of the standard library is dedicated to this topic that we 
sometimes have the feeling it deals with little else. The resulting model is way more 
extensible than what you may be used to from other languages, hut it’s also quite 
complex. 

In this chapter, we’re going to take a look at the major collection types Swift ships with, 
with a focus on how to work with them effectively and idiomatically. In the next chapter, 
we’ll climb up the abstraction ladder and see how the collection protocols in the 
standard library work. 


Arrays 

Arrays and Mutability 

Arrays are the most common collections in Swift. An array is an ordered container of 
elements that all have the same type, with random access to each element. As an 
example, to create an array of numbers, we can write the following: 

//The Fibonacci numbers 
let fibs = [0,1,1,2,3, 5] 

If we try to modify the array defined above (by using append(_:), for example), we get a 
compile error. This is because the array is defined as a constant, using let. In many cases, 
this is exactly the right thing to do; it prevents us from accidentally changing the array. 

If we want the array to be a variable, we have to define it using var: 

var mutableFibs = [0,1,1,2, 3, 5] 

Now we can easily append a single element or a sequence of elements: 

mutableFibs.append(8) 

mutableFibs.append(contentsOf: [13, 21]) 

mutableFibs//fO, 7, 7,2, 3,5,8, 73,27] 

There are a couple of benefits that come with making the distinction between var and let. 
Constants defined with let are easier to reason about because they’re immutable. When 


you read a declaration like let fibs = ..., you know that the value of fibs will never change 
— it’s enforced by the compiler. This helps greatly when reading through code. However, 
note that this is only true for types that have value semantics. A let variable to a class 
instance (i.e. a reference type) guarantees that the reference will never change, i.e. you 
can’t assign another object to that variable. However, the object the reference points to 
can change. We’ll go into more detail on these differences in the chapter on structs and 
classes. 

Arrays, like all collection types in the standard library, have value semantics. When you 
assign an existing array to another variable, the array contents are copied over. For 
example, in the following code snippet, x is never modified: 

varx = [1,2,3] 
var y = X 
y.append(4) 
y///■1,2, 3,4] 

X// [1,2,3] 

The statement var y = x makes a copy of x, so appending 4 to y won’t change x — the 
value of X will still be [1,2,3]. The same thing happens when you pass an array into a 
function; the function gets a local copy, and any changes it makes don’t affect the caller. 

Contrast this with the approach to mutability taken by NSArray in Foundation. NSArray 
has no mutating methods — to mutate an array, you need an NSMutableArray. But just 
because you have a non-mutating NSArray reference does not mean the array can’t be 
mutated underneath you: 

let a = NSMutableArray(array: [1,2,3]) 

//1 don't want to be able to mutate b 
let b: NSArray = a 

// But it can still be mutated — via a 
a.insert(4, at: 3) 
b//('t,2, 3,4) 

The correct way to write this is to manually create a copy upon assignment: 

letc = NSMutableArray(array: [1,2,3]) 

//1 don't want to be able to mutate d 
let d = c.copyO as! NSArray 
c.insert(4, at: 3) 
d//(l,2,3) 


In the example above, it’s very clear that we need to make a copy — a Is mutable, after all. 
However, when passing around arrays between methods and functions, this Isn’t always 
so easy to see. 

In Swift, there’s just one array type, and mutability is controlled by declaring with var 
instead of let. But there’s no reference sharing — when you declare a second array with 
let, you’re guaranteed it’ll never change. 

Making so many copies could be a performance problem, but in practice, all collection 
types in the Swift standard library are implemented using a technique called 
copy-on-write, which makes sure the data is only copied when necessary. So in our 
example, x and y shared internal storage up the point where y.append was called. In the 
chapter on structs and classes, we’ll take a deeper look at value semantics, including 
how to implement copy-on-write for your own types. 


Arrays and Optionals 

Swift arrays provide all the usual operations you’d expect, like isEmpty and count. Arrays 
also allow for direct access of elements at a specific index through subscripting, like 
fibs [3]. Keep in mind that you need to make sure the index is within bounds before 
getting an element via subscript. Fetch the element at index 3, and you’d better be sure 
the array has at least four elements in it. Otherwise, your program will trap, i.e. abort 
with a fatal error. 

The reason for this is mainly driven by how array indices are used. It’s pretty rare in 
Swift to actually need to calculate an index: 

-> Want to iterate over the array? 
for X in array 

-> Want to iterate over all but the first element of an array? 
forx in array.dropFirstO 

-> Want to iterate over all but the last 5 elements? 
forx in array.dropLast(5) 

-> Want to number all the elements in an array? 
for (num, element) in collection.enumeratedO 

-> Want to find the location of a specific element? 
if let idx = array.index {someMatchingLogic($0)} 



-> Want to transform all the elements In an array? 
array.map {someTransformation($0)} 

-> Want to fetch only the elements matching a specihc criterion? 
array.filter {someCriteria($0)} 

Another sign that Swift wants to discourage you from doing index math Is the removal of 
traditional C-style for loops from the language in Swift 3. Manually hddling with indices 
is a rich seam of bugs to mine, so it’s often best avoided. And if it can’t he, well, we’ll see 
in the generics chapter that it’s easy enough to write a new reusable general function 
that does what you need and in which you can wrap your carefully tested index 
calculations. 

But sometimes you do have to use an index. And with array indices, the expectation is 
that when you do, you’ll have thought very carefully about the logic behind the index 
calculation. So to have to unwrap the value of a subscript operation is probably overkill 
— it means you don’t trust your code. But chances are you do trust your code, so you’ll 
probably resort to force-unwrapping the result, because you know that the index must 
be valid. This is (a) annoying, and (b) a bad habit to get into. When force-unwrapping 
becomes routine, eventually you’re going to slip up and force-unwrap something you 
don’t mean to. So to avoid this habit becoming routine, arrays don’t give you the option. 


While a subscripting operation that responds to a invalid index with a 
controlled crash could arguably be called unsafe, that’s only one aspect of 
safety. Subscripting is totally safe in regard to memory safety — the standard 
library collections always perform bounds checks to prevent unauthorized 
memory access with an out-of-bounds index. 


Other operations behave differently. The first and last properties have an optional type; 
they return nil if the array is empty, first is equivalent to is Empty ? nil: self[0]. Similarly, 
the re move Last method will trap if you call it on an empty array, whereas pop Last will 
only delete and return the last element if the array isn’t empty, and will otherwise do 
nothing and return nil. Which one you’d want to use depends on your use case. When 
you’re using the array as a stack, you’ll probably always want to combine checking for 
empty and removing the last entry. On the other hand, if you already know through 
invariants whether or not the array is empty, dealing with the optional is fiddly. 


We’ll encounter these tradeoffs again later in this chapter when we talk about 
dictionaries. Additionally, there’s an entire chapter dedicated to optionals. 



Transforming Arrays 

Map 

It’s common to need to perform a transformation on every value in an array. Every 
programmer has written similar code hundreds of times: create a new array, loop over all 
elements in an existing array, perform an operation on an element, and append the 
result of that operation to the new array. For example, the following code squares an 
array of integers: 

var squared: [Int] = [] 
for fib in fibs { 
squared.append(fib * fib) 

} 

squared ' 7 [ 0 , 7, 7,4, 9 , 25 ] 

Swift arrays have a map method, adopted from the world of functional programming. 
Here’s the exact same operation, using map: 

let squares = fibs.map {fib in fib * fib} 
squares //[ 0 , 7, 7,4, 9, 25 ] 

This version has three main advantages. It’s shorter, of course. There’s also less room for 
error. But more importantly, it’s clearer. All the clutter has been removed. Once you’re 
used to seeing and using map everywhere, it acts as a signal — you see map, and you 
know immediately what’s happening: a function is going to be applied to every element, 
returning a new array of the transformed elements. 

The declaration of squared no longer needs to be made with var, because we aren’t 
mutating it any longer — it’ll be delivered out of the map fully formed, so we can declare 
squares with let, if appropriate. And because the type of the contents can be inferred 
from the function passed to map, squares no longer needs to be explicitly typed. 

map isn’t hard to write — it’s just a question of wrapping up the boilerplate parts of the 
for loop into a generic function. Here’s one possible Implementation (though in Swift, 
it’s actually an extension of Sequence, something we’ll cover in the chapter on writing 
generic algorithms): 

extension Array { 

func map<T>(_ transform: (Element) -> T) -> [T] { 


var result: [T] = [] 
result.reserveCapacity(count) 

forx in self { 

result.append(transform(x)) 

} 

return result 

} 


Element is the generic piacehoider for whatever type the array contains. And T is a new 
piacehoider that can represent the resuit of the eiement transformation. The map 
function itseif doesn’t care what Element and T are; they can be anything at ail. The 
concrete type T of the transformed elements is defined by the return type of the 
transform function the caller passes to map. 


Really, the signature of this method should be 

func map<T>(_ transform: (Element) throws -> T) rethrows -> [T], indicating that 
map will forward any error the transformation function might throw to the 
caller. We’ll cover this in detail in the errors chapter. We’ve left the error 
handling annotations out here for simplicity. If you’d like, you can check out 
the source code for Sequence.map in the Swift repository on GitHub. 


Parameterizing Behavior with Functions 

Even if you’re already familiar with map, take a moment and consider the map code. 
What makes it so general yet so useful? 

map manages to separate out the boilerplate — which doesn’t vary from call to call — 
from the functionality that always varies: the logic of how exactly to transform each 
element. It does this through a parameter the caller supplies: the transformation 
function. 

This pattern of parameterizing behavior is found throughout the standard library. There 
are more than a dozen separate functions that take a function that allows the caller to 
customize the key step: 


^ map and flatMap — how to transform an element 




-> filter — should an element be included? 

-> reduce — how to fold an element into an aggregate value 

-> sequence — what should the next element of the sequence be? 

-> forEach — what side effect to perform with an eiement 

-> sort, lexicographicallyPrecedes, and partition — in what order shouid two 
eiements come? 

-> index, first, and contains — does this eiement match? 

-> min and max — which is the min/max of two eiements? 

-> elementsEqual and starts — are two eiements equivaient? 

-> split — is this eiement a separator? 

-> prefix — fliter eiements whiie a predicate returns true, then drop the rest (simiiar 
to filter, but with an early exit, and useful for infinite or iaziiy computed 
sequences) 

-> drop — drop eiements untii the predicate ceases to be true, and then return the 
rest (similar to prefix, but this returns the inverse) 

The goai of ail these functions is to get rid of the ciutter of the uninteresting parts of the 
code, such as the creation of a new array, the for loop over the source data, and the like. 
Instead, the clutter is replaced with a single word that describes what’s being done. This 
brings the important code - the logic the programmer wants to express - to the 
forefront. 

Several of these functions have a default behavior, sort sorts elements in ascending 
order when they’re comparable, unless you specify otherwise, contains can take a value 
to check for, so long as the elements are equatable. These defaults help make the code 
even more readable. Ascending order sort is natural, so the meaning of array.sort() is 
intuitive. array.index(of: "foo") is clearer than array.index {$0 == "foo"}. 

But in every instance, these are just shorthand for the common cases. Elements don’t 
have to be comparable or equatable, and you don’t have to compare the whole element — 
you can sort an array of people by their ages (people.sort {$0.age < $1 .age}) or check if 
the array contains anyone underage (people.contains {$0.age < 18}). You can also 
compare some transformation of the element. For example, an admittedly inefficient 
case-insensitive sort could be performed via 
people.sort {$0.name.uppercased() < $1 .name.uppercasedO }. 



There are other functions of similar usefulness that would also take a function to specify 
their behaviors but aren’t in the standard library. You could easily define them yourself 
(and might like to try): 

^ accumulate — combine elements into an array of running values (like reduce, but 
returning an array of each interim combination) 

-> all(matching:) and none(matching:) — test if all or no elements in a sequence 
match a criterion (can be built with contains, with some carefully placed 
negation) 

-> count(where:) — count the number of elements that match (similar to filter, but 
without constructing an array) 

-> indices(where:) — return a list of indices matching a criteria (similar to 
index(where:), but doesn’t stop on the first one) 

Some of these we define elsewhere in the book. 

You might find yourself writing something that fits a pattern more than a couple of times 
— something like this, where you search an array in reverse order for the first element 
that matches a certain condition: 

let names = ["Paula", "Elena", "Zee"] 
var lastNameEndingInA: String? 

for name in names.reversed!) where name.hasSuffixC'a") { 
lastNameEndingInA = name 

break 

} 

lastNameEndingInA //Opt/ono/("E/ena") 

If that’s the case, consider writing a short extension to Sequence. The method 
last(where:) wraps this logic — we use a function argument to abstract over the part of 
our for loop that varies: 

extension Sequence { 

func last(where predicate:(Element) -> Bool) -> Element?! 
for element in reversed!) where predicate(element) { 
return element 

} 

return nil 


} 


} 


This then allows you to replace your for loop with the following: 

let match = names.last {$0.hasSuffix("a'')} 
match //OptionalC'Elena") 

This has all the same benehts we described for map. The example with last(where:) is 
more readable than the example with the for loop; even though the for loop is simple, 
you still have to run the loop through in your head, which is a small mental tax. Using 
last(where:) introduces less chance of error (such as accidentally forgetting to reverse 
the array), and it allows you to declare the result variable with let instead of var. 

It also works nicely with guard — in all likelihood, you’re going to terminate a flow early 
if the element isn’t found: 

guard let match = someSequence.last(where: {$0.passesTest()}) 

else { return } 

//Do something with match 

We’ll say more about extending collections and using functions later in the book. 


Mutation and Stateful Closures 

When iterating over an array, you could use map to perform side effects (e.g. inserting 
the elements into some lookup table). We don’t recommend doing this. Take a look at 
the following: 

array.map {item in 
table.insert(item) 

} 

This hides the side effect (the mutation of the lookup table) in a construct that looks like 
a transformation of the array. If you ever see something like the above, then it’s a clear 
case for using a plain for loop instead of a function like map. The forEach method would 
also be more appropriate than map in this case, but it has its own issues. We’ll look at 
forEach in a bit. 


Performing side effects is different than deliberateiy giving the closure local state, which 
is a particularly useful technique, and it’s what makes closures — functions that can 
capture and mutate variables outside their scope — so powerful a tool when combined 
with higher-order functions. For example, the accumulate function described above 
could be implemented with map and a stateful closure, like this: 

extension Array { 

func accumulate<Result>(_ initialResult: Result, 

_ nextPartialResult: (Result, Element) -> Result) -> [Result] 

{ 

var running = initialResult 
return map { next in 

running = nextPartialResult(running, next) 
return running 

} 

} 

} 

This creates a temporary variable to store the running value and then uses map to create 
an array of the running values as the computation progresses: 

[1,2,3,4].accumulate(0, -t) // [ 1 , 3 , 6 , 10 ] 

Note that this code assumes that map performs its transformation in order over the 
sequence. In the case of our map above, it does. But there are possible implementations 
that could transform the sequence out of order — for example, one that performs the 
transformation of the elements concurrently. The official standard library version of 
map doesn’t specify whether or not it transforms the sequence in order, though it seems 
like a safe bet. 


Filter 

Another very common operation is to take an array and create a new array that only 
includes those elements that match a certain condition. The pattern of looping over an 
array and selecting the elements that match the given predicate is captured in the filter 
method: 

let nums = [1,2,3,4,5,6,7,8,9,10] 
n urns.filter {numinnum%2==0}/7/'2,4, 6, 8, 7 Oj 


We can use Swift’s shorthand notation for arguments of a ciosure expression to make 
this even shorter. Instead of naming the num argument, we can write the above code iike 
this: 

nums.filter {$0 % 2 == 0} //[ 2 , 4, 6, 8, 10 ] 

For very short ciosures, this can be more readabie. If the closure is more compiicated, 
it’s aimost aiways a better idea to name the arguments expiicitiy, as we’ve done before. 
It’s really a matter of personal taste — choose whichever is more readable at a glance. A 
good rule of thumb is this: if the closure fits neatly on one line, shorthand argument 
names are a good fit. 

By combining map and filter, we can easily write a lot of operations on arrays without 
having to introduce a single intermediate variable, and the resulting code will become 
shorter and easier to read. For example, to And all squares under 100 that are even, we 
could map the range 0..<10, in order to square it, and then Alter out all odd numbers: 

(1 ..<10).map {$0 * $0 j.filter {$0 % 2 = = 0 }//f4, 76, 36, 64] 

The implementation of filter looks much the same as map: 
extension Array { 

func filterL isincluded: (Element) -> Bool) -> [Element] { 
var result: [Element] = [] 
forx in self where islncluded(x) { 
result.append(x) 

} 

return result 

} 

} 

For more on the where clause we use in the for loop, see the optionals chapter. 

One quick performance tip: if you ever And yourself writing something like the 
following, stop! 

bigArray.filter {someCondition }.count > 0 

filter creates a brand new array and processes every element in the array. But this is 
unnecessary. This code only needs to check if one element matches — in which case, 
contains(where:) will do the job: 


bigArray.contains {someCondition} 


This is much faster for two reasons: it doesn’t create a whole new array of the Altered 
elements just to count them, and it exits early, as soon as it Ands the Arst match. 
Generally, only ever use filter if you want all the results. 

Often you want to do something that can he done with contains, but it looks pretty ugly. 
For example, you can check if every element of a sequence matches a predicate using 
isequence.contains {Icondition}, but it’s much more readable to wrap this in a new 
function that has a more descriptive name: 

extension Sequence { 

public func aU(matching predicate: (Element) -> Bool) -> Bool { 

// Every element matches a predicate if no element doesn't match it: 
return 'contains {!predicate($0)} 

} 

} 

let evenNums = nums.filter {$0 % 2 == 0} // [2,4, 6, 8, 10] 
evenNums.all {$0 % 2 == 0} //true 


Reduce 

Both map and filter take an array and produce a new, modlAed array. Sometimes, 
however, you want to combine all elements into a new value. For example, to sum up all 
the elements, we could write the following code: 

let fibs = [0,1,1,2,3, 5] 
var total = 0 
for num in fibs { 
total = total + num 

} 

total//72 

The reduce method takes this pattern and abstracts two parts: the initial value (in this 
case, zero), and the function for combining the intermediate value (total) and the 
element (num). Using reduce, we can write the same example like this: 

let sum = fibs.reduce(O) {total, num in total + num] // 12 


Operators are functions too, so we could’ve also written the same example like this: 
fibs.reduce(0, +) // 72 

The output type of reduce doesn’t have to be the same as the element type. For example, 
if we want to convert a list of integers into a string, with each number followed by a 
space, we can do the following: 

fibs.reduceC"') {str, num in str + "\(num), "} //O, 1, 7,2, 3, 5, 

Here’s the implementation for reduce: 
extension Array { 

func reduce<Result>(_ initialResult: Result, 

_ nextPartialResult: (Result, Element) -> Result) -> Result 

{ 

var result = initialResult 
forx in self { 

result = nextPartialResult(result, x) 

} 

return result 

} 

} 

Another performance tip: reduce is very flexible, and it’s common to see it used to build 
arrays and perform other operations. For example, you can Implement map and filter 
using only reduce: 

extension Array { 

func map2<T>(_ transform: (Element) -> T) -> [T] { 
return reduce([]) { 

$0 + [transform($1)] 

} 

} 

func filter2(_ isincluded: (Element) -> Bool) -> [Element] { 
return reduce([]) { 
islncluded($1)?$0 + [$1] :$0 

} 

} 

} 


This is kind of beautifui and has the benefit of not needing those icky imperative for 
ioops. But Swift isn’t Haskeii, and Swift arrays aren’t iists. What’s happening here is that 
every time, through the combine function, a brand new array is being created by 
appending the transformed or inciuded eiement to the previous one. This means that 
both these impiementations are O(n^), not 0(n) — as the iength of the array increases, 
the time these functions take increases quadraticaiiy. 

There’s a second version of reduce, which has a different type. Specihcaiiy, the function 
for combining an intermediate resuit and an eiement now takes Result as an inout 
parameter: 

public func reduce<Result>(into initialResult: Result, 

_ updateAccumulatingResult: 

(_ partialResult: inout Result, Element) throws -> () 

) rethrows -> Result 

We discuss inout parameters in detaii in the chapter on structs and ciasses, but for now, 
think of the inout Result parameter as a mutable parameter: we can modify it within the 
function. This allows us to write filter in a much more efficient way: 

extension Array { 

func filter3(_ isincluded: (Element) -> Bool) -> [Element] { 
return reduce(into: []) {result, element in 
if islncluded(element) { 
result.append(element) 

} 

} 

} 

} 

When using inout, the compiler doesn’t have to create a new array each time, so this 
version of filter is again 0(n). When the call to reduce(into:_:) is inllned by the compiler, 
the generated code is often the same as when using a for loop. 


A Flattening Map 


Sometimes, you want to map an array where the transformation function returns 
another array and not a single element. 


For example, let’s say we have a function, links, which reads a Markdown file and returns 
an array containing the URLs of all the links in the file. The function type looks like this: 

func extractLinksfmarkdownFile: String) -> [URL] 

If we have a bunch of Markdown files and want to extract the links from all files into a 
single array, we could try to write something like markdownFiles.map(extractLinks). But 
this returns an array of arrays containing the URLs: one array per file. Now you could 
just perform the map, get back an array of arrays, and then call joined to flatten the 
results into a single array: 

let markdownFiles: [String] = 

let nestedLinks = markdownFiles.map(extractLinks) 
let links = nestedLinks.joinedQ 

The flatMap method combines these two operations into a single step. So 
markdownFiles.flatMap(extractLinks) returns all the URLs in an array of Markdown files 
as a single array. 

The signature for flatMap is almost Identical to map, except its transformation function 
returns an array. The implementation uses append(contentsOf:) instead of append(_:) to 
flatten the result array: 

extension Array { 

func flatMap<T>(_ transform: (Element) -> [T]) -> [T] { 
var result: [T] = [] 
forx in self { 

result.append(contentsOf: transform(x)) 

} 

return result 

} 


Another great use case for flatMap is combining elements from different arrays. To get 
all possible pairs of two arrays, flatMap over one array and then map over the other: 

let suits = "V, "A", "♦''] 

let ranks = ["J'V'Q'',"K",''A"] 
let result = suits.flatMap {suit in 
ranks.map {rank in 


(suit, rank) 


} 

} 

/* 

"J"), "Q"), ("*>", "K"), "A"), "J"), ("¥" 

"Q"), "K"), "A"), "J"), "Q"), "K"), 

"A"), ("♦ " "J"), ("♦" "Q"), ("^", "K"), ("♦" "A")] 

*/ 


Iteration using forEach 

The final operation we’d like to discuss is forEach. It works almost like a for loop: the 
passed-in function is executed once for each element in the sequence. And unlike map, 
forEach doesn’t return anything. Let’s start hy mechanically replacing a loop with 
forEach: 

for element in [1,2,3] { 
print(element) 

} 

[1,2,3]. forEach {element in 
print(element) 

} 

This isn’t a big win, but it can be handy if the action you want to perform is a single 
function call on each element in a collection. Passing a function name to forEach 
instead of a closure expression can lead to clear and concise code. For example, if you’re 
Inside a view controller and want to add an array of subviews to the main view, you can 
just do theViews.forEach(view.addSubview). 

However, there are some subtle differences between for loops and forEach. For instance, 
if a for loop has a return statement in it, rewriting it with forEach can significantly 
change the code’s behavior. Consider the following example, which is written using a for 
loop with a where condition: 

extension Array where Element: Equatable { 
func index(of element: Element) -> Int? { 
for idx in self.indices where self[idx] == element { 


return idx 


} 

return nil 

} 


We can’t directly replicate the where clause in the forEach construct, so we might 
(incorrectly) rewrite this using filter: 

extension Array where Element: Equatable { 
func index_foreach(of element: Element) -> Int? { 
self.indices. filter {idx in 
self[idx] == element 
}.forEach {idx in 
return idx 

} 

return nil 

} 


The return inside the forEach closure doesn’t return out of the outer function; it only 
returns from the closure Itself. In this particular case, we’d probably have found the bug 
because the compiler generates a warning that the argument to the return statement is 
unused, but you shouldn’t rely on it finding every such issue. 

Also, consider the following simple example: 

(1 ..<10).forEach { number in 
print(number) 
if number > 2 { return } 

} 

It’s not immediately obvious that this prints out all the numbers in the input range. The 
return statement isn’t breaking the loop, rather it’s returning from the closure. 

In some situations, such as the addSubview example above, forEach can be nicer than a 
for loop. However, because of the non-obvlous behavior with return, we recommend 
against most other uses of forEach. Just use a regular for loop instead. 


Array Types 


Slices 

In addition to accessing a single element of an array by subscript (e.g. fibs[0]), we can 
also access a range of elements by subscript. For example, to get all but the first element 
of an array, we can do the following: 

let slice = fibs[1...] 
slice//ff, 1,2, 3,5] 
type(of: slice) // ArraySlice<lnt> 

This gets us a slice of the array starting at the second element. The type of the result is 
ArraySlice, not Array. ArraySlice is a view on arrays. It’s backed by the original array, yet 
it provides a view on just the slice. This makes certain the array doesn’t need to get 
copied. The ArraySlice type has the same methods defined as Array does, so you can use 
a slice as if it were an array. If you do need to convert a slice into an array, you can just 
construct a new array out of the slice: 

let newArray = Array(slice) 
typefof: newArray) //Array<lnt> 



Figure 2.1; Array Slices 


















Bridging 


Swift arrays can bridge to Objective-C. They can aiso be used with C, hut we’ii cover that 
in a iater chapter. Because NSArray can oniy hold objects, the compiler and runtime will 
automatically wrap incompatible values (for example, Swift enums) in an opaque box 
object. A number of value types (such as Int, Bool, and String, but also Dictionary and 
Set) are bridged automatically to their Ohjective-C counterparts. 


A universal bridging mechanism for all Swift types to Objective-C doesn’t just 
make working with arrays more pleasant. It also applies to other collections, 
like dictionaries and sets, and it opens up a lot of potential for future 
enhancements to the interoperability between Swift and Objective-C. For 
example, a future Swift version might allow Swift value types to conform to 
@objc protocols. 


Dictionaries 


Another key data structure is Dictionary. A dictionary contains keys with corresponding 
values; duplicate keys aren’t supported. Retrieving a value by its key takes constant time 
on average, whereas searching an array for a particular element grows linearly with the 
array’s size. Unlike arrays, dictionaries aren’t ordered. The order in which pairs are 
enumerated in a for loop is undehned. 

In the following example, we use a dictionary as the model data for a hctional settings 
screen in a smartphone app. The screen consists of a list of settings, and each individual 
setting has a name (the keys in our dictionary) and a value. A value can be one of several 
data types, such as text, numbers, or booleans. We use an enum with associated values to 
model this: 

enum Setting { 
case text(String) 
case int(lnt) 
case bool(Bool) 

} 

let defaultSettings: [StringiSetting] = [ 

"Airplane Mode": .bool(false), 

"Name": .textC'My iPhone"), 


] 



defaultSettings["Name"] /^Opt/ono/(Sett/ng.textC'My iPhone")) 


We use subscripting to get the value of a setting. Dictionary lookup always returns an 
optional value — when the specified key doesn’t exist, it returns nil. Contrast this with 
arrays, which respond to an out-of-bounds access by crashing the program. 

The rationale for this difference is that array indices and dictionary keys are used very 
differently. We’ve already seen that it’s quite rare that you actually need to work with 
array indices directly. And if you do, an array index is usually directly derived from the 
array in some way (e.g. from a range like 0..<array.count); thus, using an invalid index is 
a programmer error. On the other hand, it’s very common for dictionary keys to come 
from some source other than the dictionary itself. 

Unlike arrays, dictionaries are also sparse. The existence of the value under the key 
"name" doesn’t tell you anything about whether or not the key “address” also exists. 


Mutation 

Just like with arrays, dictionaries defined using let are immutable: no entries can be 
added, removed, or changed. And just like with arrays, we can define a mutable variant 
using var. To remove a value from a dictionary, we can either set it to nil using 
subscripting or call removeValuefforKey:). The latter additionally returns the deleted 
value, or nil if the key didn’t exist. If we want to take an immutable dictionary and make 
changes to it, we have to make a copy: 

var userSettings = defaultSettings 
userSettings["Name"] = .textC'Jared's iPhone") 
userSettings[''Do Not Disturb"] = .bool(true) 

Note that, again, the value of defaultSettings didn’t change. As with key removal, an 
alternative to updating via subscript is the updateValue(_:forKey:) method, which 
returns the previous value (if any): 

let oldName = userSettings 
.updateValue(.text("Jane's iPhone"), forKey: "Name") 
userSettings[''Name"] // Optional(Setting.text("Jane\'s iPhone")) 
oldName Optional(Setting.text("Jared\'s iPhone")) 


Some Useful Dictionary Methods 


What if we wanted to combine the default settings dictionary with any custom settings 
the user has changed? Custom settings should override defaults, but the resulting 
dictionary should still include default values for any keys that haven’t been customized. 
Essentially, we want to merge two dictionaries, where the dictionary that’s being merged 
in overwrites duplicate keys. 

Dictionary has a merge(_:uniquingKeysWith:) method, which takes the key-value pairs to 
be merged in and a function that specifies how to combine two values with the same key. 
We can use this to merge one dictionary into another, as shown in the following 
example: 

var settings = defaultSettings 

let overriddenSettings: [StringiSetting] = ["Name": .textC'Jane's iPhone")] 
settings.merge(overriddenSettings, uniquingKeysWith: {$1 }) 
settings 

//["Name": Setting.text("Jane\'s iPhone"), "Airplane Mode": Setting.bool(false)] 

In the example above, we used {$1} as the policy for combining two values. In other 
words, in case a key exists in both settings and overriddenSettings, we use the value from 
overriddenSettings. 

We can also construct a new dictionary out of a sequence of (Key,Value) pairs. If we 
guarantee that the keys are unique, we can use Dictionary(uniqueKeysWithValues:). 
However, in case we have a sequence where a key can exist multiple times, we need to 
provide a function to combine two values for the same keys, just like above. For example, 
to compute how often elements appear in a sequence, we can map over each element, 
combine it with a 1, and then create a dictionary out of the resulting element-frequency 
pairs. If we encounter two values for the same key (in other words, if we saw the same 
element more than once), we simply add the frequencies up using -t: 

extension Sequence where Element: Hashable { 
var frequencies: [Element:int] { 
let frequencyPairs = self.map {($0,1)} 
return Dictionary(frequencyPairs, uniquingKeysWith:-)-) 

} 

} 

let frequencies = "hello".frequencies// ["e": 7, "o": 7, "I":2, "h": 7j 
frequencies.filter {$0.value > 1 ]//["l":2] 


Another useful method is a map over the dictionary’s values. Because Dictionary is a 
Sequence, it already has a map method that produces an array. However, sometimes we 
want to keep the dictionary structure intact and only transform its values. The 
mapValues method does just this: 

let settingsAsStrings = settings.mapValues {setting -> String in 
switch setting { 
case .text(let text): return text 
case .int(let number): return String(number) 
case .bool(let value): return String(value) 

} 

} 

settingsAsStrings ["Nome"; "Jane\'s iPhone", "Airplane Mode": "false"] 


Hashable Requirement 

Dictionaries are hash tables . The dictionary assigns each key a position in its underlying 
storage array based on the key’s hashValue. This is why Dictionary requires its Key type 
to conform to the Hashable protocol. All the basic data types in the standard library 
already do, including strings, integers, floating-point, and Boolean values. 

Enumerations without associated values also get automatic Hashable conformance for 
free. 

If you want to use your own custom types as dictionary keys, you must add Hashable 
conformance manually. This requires an implementation of the hashValue property and, 
because Hashable extends Equatable, an overload of the == operator function for your 
type. Your implementation must hold an important invariant: two instances that are 
equal (as defined by your = = implementation) must have the same hash value. The 
reverse isn’t true: two instances with the same hash value don’t necessarily compare 
equally. This makes sense, considering that there’s only a finite number of distinct hash 
values, while many hashable types (like strings) have essentially infinite cardinality. 

The potential for duplicate hash values means that Dictionary must be able to handle 
collisions. Nevertheless, a good hash function should strive for a minimal number of 
collisions in order to preserve the collection’s performance characteristics, i.e. the hash 
function should produce a uniform distribution over the full integer range. In the 
extreme case where your implementation returns the same hash value (e.g. zero) for 
every instance, a dictionary’s lookup performance degrades to 0(n). 



The second characteristic of a good hash function is that it’s fast. Keep in mind that the 
hash vaiue is computed every time a key is inserted, removed, or looked up. If your 
hashValue impiementation takes too much time, it might eat up any gains you got from 
the 0(1) compiexity. 

Writing a good hash function that meets these requirements isn’t easy. Fortunateiy, soon 
we won’t have to do this ourseives in most situations, as there’s an accepted proposal for 
s ynthesizing Equatable and Hashable conformance . Once this feature is fully 
implemented and merged, we can instruct the compiler to automatically generate both 
Equatable and Hashable conformance for our custom types. 

Finally, be extra careful when you use types that don’t have value semantics 
(e.g. mutable objects) as dictionary keys. If you mutate an object after using it as a 
dictionary key in a way that changes its hash value and/or equality, you’ll not be able to 
hnd it again in the dictionary. The dictionary now stores the object in the wrong slot, 
effectively corrupting its internal storage. This isn’t a problem with value types because 
the key in the dictionary doesn’t share your copy’s storage and therefore can’t he 
mutated from the outside. 


Sets 


The third major collection type in the standard library is Set. A set is an unordered 
collection of elements, with each element appearing only once. You can essentially 
think of a set as a dictionary that only stores keys and no values. Like Dictionary, Set is 
implemented with a hash table and has similar performance characteristics and 
requirements. Testing a value for membership in the set is a constant-time operation, 
and set elements must be Hashable, just like dictionary keys. 

Use a set instead of an array when you need to test efficiently for membership (an 0{n) 
operation for arrays) and the order of the elements is not important, or when you need to 
ensure that a collection contains no duplicates. 

Set conforms to the ExpressibleByArrayLiteral protocol, which means that we can 
initialize it with an array literal like this: 

let naturals: Set =[1,2,3, 2] 
naturals // (2, 3, 1] 
naturals.contains(3) //true 
naturals.contains(O) /Yfo/se 



Note that the number 2 appears only once in the set; the duplicate never even gets 
inserted. 

Like all collections, sets support the common operations we’ve already seen: you can 
iterate over the elements in a for loop, map or filter them, and do all other sorts of things. 


Set Algebra 

As the name implies. Set is closely related to the mathematical concept of a set; it 
supports all common set operations you learned in math class. For example, we can 
subtract one set from another: 

let iPods: Set = ["iPod touch", "iPod nano", "iPod mini", 

"iPod shuffle", "iPod Classic"] 
let discontinuedIPods: Set = ["iPod mini", "iPod Classic", 

"iPod nano", "iPod shuffle"] 

let currentIPods = iPods.subtracting(discontinuedlPods) /^f'/Pod touch"] 

We can also form the intersection of two sets, i.e. find all elements that are in both: 

let touchscreen: Set = ["iPhone", "iPad", "iPod touch", "iPod nano"] 
let iPodsWithTouch = iPods.intersection(touchscreen) 

//["iPod touch", "iPod nano"] 

Or, we can form the union of two sets, i.e. combine them into one (removing duplicates, 
of course): 

var discontinued: Set = ["iBook", "Powerbook", "Power Mac"] 
discontinued.formUnion(discontinuedI Pods) 
discontinued 
/* 

["iBook", "Powerbook", "Power Mac", "iPod Classic", "iPod mini", 

"iPod shuffle", "iPod nano"] 

*/ 


Here, we used the mutating variant form Union to mutate the original set (which, as a 
result, must be declared with var). Almost all set operations have both non-mutating 
and mutating forms, the latter beginning with form.... For even more set operations, 
check out the SetAlgebra protocol. 


Index Sets and Character Sets 


Set and OptionSet are the only types in the standard library that conform to SetAlgebra, 
but the protocol is also adopted by two interesting types in Foundation: IndexSet and 
CharacterSet. Both of these date back to a time long before Swift was a thing. The way 
these and other Objective-C classes are now bridged into Swift as fully featured value 
types — adopting common standard library protocols in the process — is great because 
they’ll instantly feel familiar to Swift developers. 

IndexSet represents a set of positive integer values. You can, of course, do this with a 
Set<lnt>, but IndexSet is more storage efficient because it uses a list of ranges internally. 
Say you have a table view with 1,000 elements and you want to use a set to manage the 
indices of the rows the user has selected. A Set<lnt> needs to store up to 1,000 elements, 
depending on how many rows are selected. An IndexSet, on the other hand, stores 
continuous ranges, so a selection of the first 500 rows in the table only takes two 
integers to store (the selection’s lower and upper bounds). 

However, as a user of an IndexSet, you don’t have to worry about the Internal structure, 
as it’s completely hidden behind the familiar SetAlgebra and Collection interfaces. 
(Unless you want to work on the ranges directly, that is. IndexSet exposes a view to them 
via its rangeView property, which itself is a collection.) For example, you can add a few 
ranges to an index set and then map over the indices as if they were individual 
members: 

var indices = IndexSetQ 
indices.insert(integersln: 1 ..<5) 
indices.insert(integersln: 11 ..<15) 

let even Indices = indices.filter { $0 % 2 == 0}// [2,4, 12, 14] 

CharacterSet is an equally efficient way to store a set of Unicode code points. It’s often 
used to check if a particular string only contains characters from a specific character 
subset, such as alphanumerics or decimalDigits. However, unlike IndexSet, CharacterSet 
isn’t a collection. The name CharacterSet, imported from Objective-C, is also 
unfortunate in Swift because CharacterSet isn’t compatible with Swift’s Character type. 
A better name would be UnicodeScalarSet. We’ll talk a bit more about CharacterSet in 
the chapter on strings. 


Using Sets Inside Closures 

Dictionaries and sets can be very handy data structures to use inside your functions, 
even when you’re not exposing them to the caller. For example, if we want to write an 
extension on Sequence to retrieve all unique elements in the sequence, we could easily 
put the elements in a set and return its contents. However, that won’t be stable: because 
a set has no defined order, the input elements might get reordered in the result. To fix 
this, we can write an extension that maintains the order by using an internal Set for 
bookkeeping: 

extension Sequence where Element: Hashable { 
func uniqueQ -> [Element] { 
var seen: Set<Element> = [] 
return filter {element in 
if seen.contains(element) { 
return false 
} else { 

seen.insert(element) 

return true 

} 

} 

} 

} 

[1,2,3,12,1,3,4,5,6,4,6].unique])//ft, 2, 3, 72,4, 5,6] 

The method above allows us to find all unique elements in a sequence while still 
maintaining the original order (with the constraint that the elements must be Hashable). 
Inside the closure we pass to filter, we refer to the variable seen that we defined outside 
the closure, thus maintaining state over multiple iterations of the closure. In the chapter 
on functions, we’ll look at this technique in more detail. 


Ranges 

A range is an interval of values, defined by its lower and upper bounds. You create 
ranges with the two range operators: ..< for half-open ranges that don’t include their 
upper bound, and ... for closed ranges that include both bounds: 


//0to9, 10 is not included 


let singleDigitNumbers = O.XIO 
Array(singleDigitNumbers) /^fO, 7,2, 3, 4, 5, 6, 7, 8, 9] 

// "z" is included 

let lowercaseLetters = Character("a")...Character("z'') 

There are also prefix and postfix variants of these operators, used to express one-sided 
ranges: 

let fromZero = 0... 

let upToZ = ..<Character("z'') 

There are eight distinct concrete types that represent ranges, and each type captures 
different constraints on the value. The two most essential types are Range (a half-open 
range, created using ..<) and ClosedRange (created using ...). Both have a generic Bound 
parameter: the only requirement is that Bound must be Comparable. For example, the 
lowercaseLetters expression above is of type Closed Range<Character>. Somewhat 
surprisingly, we can’t iterate over Range and ClosedRange, but we can check whether 
elements are contained within the range: 

singleDigitNumbers.contains(9) // true 
lowercaseLetters.overlapsC'c".. <''f'') T'true 

(The answer why iterating over characters isn’t as straightforward as it would seem has 
to do with Unicode, and we’ll cover it at length in the chapter on strings.) 

Half-open and closed ranges both have a place: 

-> Only a half-open range can represent an empty interval (when the lower and 
upper bounds are equal, as in 5..<5). 

-> Only a elosed range can contain the maximum value its element type can 
represent (e.g. 0...1nt.max). A half-open range always requires at least one 
representable value that’s greater than the highest value in the range. 


Countable Ranges 

Ranges seem like a natural fit to be sequences or collections, so it may surprise you that 
Range and ClosedRange are neither. Some ranges are sequences, however, otherwise 
iterating over a range of integers in a for loop wouldn’t work: 


for i in O.xlO { 
print("\(i)'', terminator: " ") 

}//01 23456789 

What’s going on here? If you inspect the type of the expression 0..<10, you’li discover it’s 
CountableRange<lnt>. A CountableRange is just like a Range, with the additional 
constraint that its element type conforms to Strideable (with integer steps). Swift calls 
these more capable ranges countable because only they can be iterated over. Valid 
bounds for countable ranges include Integer and pointer types — but not floating-point 
types, because of the integer constraint on the type’s Stride. If you need to Iterate over 
consecutive floating-point values, you can use the stride(from:to:by) and 
stride(from:through:by) functions to create such a sequence. The Strideable constraint 
enables CountableRange and CountableClosedRange to conform to 
RandomAccessCollection, so we can iterate over them. 

The four basic range types we’ve discussed thus far can be classified in a two-by-two 
matrix, as follows: 


Half-open range Closed range 

Elements are Comparable Range ClosedRange 

Elements are Strideable CountableRange CountableClosedRange 

(with integer steps) 


The columns of the matrix correspond to the two range operators we saw above, which 
create a [CountablejRange (half-open) or a [CountablejClosedRange (closed), 
respectively. 

The rows in the table distinguish between “normal” ranges with an element type that 
only conforms to the Comparable protocol (which is the minimum requirement), and 
ranges over types that are Strideable and use integer steps between elements. Only the 
latter ranges are collections, inheriting all the powerful functionality we’ll see in the 
next chapter. 


Partial Ranges 

Partial ranges are constructed by using... or ..< as a prefix or a postfix operator. For 
example, 0... means the range starting at zero. These ranges are called partial because 
they’re still missing one of their bounds. There are four different kinds: 



letfromA: PartialRangeFrom<Character> = CharacterCa")... 
letthroughZ: PartialRangeThrough<Character> = ...CharacterC'z") 
let uptolO: PartialRangeUpTo<lnt> = ..<10 
let fromPive: CountablePartialRangeFrom<lnt> = 5... 

There’s only one countable variant: CountablePartialRangeFrom. It’s the only partial 
range we can iterate over. Iteration works hy starting with the lowerBound and 
repeatedly calling advanced(by: 1). If you use such a range in a for loop, you must take 
care to add a break condition lest you end up in an infinite loop (or crash when the 
counter overflows). PartialRangeFrom can’t he iterated over because its Bound is not 
Strideable, and both PartialRangeThrough and PartialRangeUpTo are missing a lower 
bound. 


Range Expressions 

All eight range types conform to the RangeExpression protocol. The protocol itself is 
small enough to print in this book. First of all, it allows you to ask whether an element is 
contained within the range. Second, given a collection, it can compute a fully specified 
Range for you: 

public protocol RangeExpression { 
associatedtype Bound: Comparable 
func contains(_ element: Bound) -> Bool 
func relative<C: _lndexable>(to collection: C) -> Range<Bound> 
where C.index == Bound 

} 

For partial ranges with a missing lower bound, the relative(to:) method adds the 
collection’s startindex as the lower bound. For partial ranges with a missing upper 
bound, it’ll use the collection’s endi ndex. Partial ranges enable a very compact syntax for 
slicing collections: 

let arr = [1,2,3,4] 
arr[2...]//f3,4j 
arr[..<1] //[I] 
arr[1...2] //[2,3] 


This works because the corresponding subscript deciaration in the Collection protocol 
takes a RangeExpression rather than one of the eight concrete range types. You can even 
omit both bounds to get a slice of the entire collection: 

arr[...]///■?, 2, 3,4] 
type(of: arr) // Array <lnt> 

(This is implemented as a special case in the standard library in Swift 4.0. Such an 
unbounded range isn’t a valid RangeExpression yet, but it should become one 
eventually.) 


Ranges and Conditional Conformance 

The standard library currently has to have separate types for countable ranges: 
CountableRange, CountableClosedRange, and CountablePartialRangeFrom. Ideally, these 
wouldn’t be distinct types, but rather extensions on Range, ClosedRange, and 
PartialRangeFrom that declare Collection conformance on the condition that the generic 
parameters meet the required constraints. We’II talk a lot more about this in the next 
chapter, but the code might look like this: 

// Invalid in Swift 4 

extension Range: RandomAccessCollection 
where Bound: Strideable, Bound.Stride: Signedinteger 

{ 

// Implement RandomAccessCollection 

} 

Alas, Swift 4’s type system can’t express this idea, so separate types are needed. Support 
for conditional conformance is expected for Swift 5, and CountableRange, 
CountableClosedRange, and CountablePartialRangeFrom will then be deprecated or 
removed from the standard library. 

The distinction between the half-open Range and the closed ClosedRange will likely 
remain, and it can sometimes make working with ranges harder than it should 
intuitively be. Say you have a function that takes a Range<Character> and you want to 
pass it the closed character range we created above. You may be surprised to hnd out it’s 
not possible! Inexplicably, there appears to be no way to convert a ClosedRange into a 
Range. But why? Weil, to turn a closed range into an equivalent half-open range, you’d 
have to hnd the element that comes after the original range’s upper bound. And that’s 



simply not possible unless the element is Strideable, which is only guaranteed for 
countable ranges. 


This means the caller of such a function will have to provide the correct type. If the 
function expects a Range, you can’t use the ... operator to create it. We’re not certain how 
big of a limitation this is in practice, since most ranges are likely integer based, but it’s 
dehnltely unintuitive. 

If possible, try copying the standard library’s approach and make your own functions 
take a RangeExpression rather than a concrete type. It’s not always possible because the 
protocol doesn’t give you access to the range’s bounds unless you’re in the context of a 
collection, hut if it is, you’ll give consumers of your APIs much more freedom to pass in 
any kind of range expression they like. 


Recap 

In this chapter, we saw a number of different collections: arrays, dictionaries, sets, index 
sets, and ranges. We also looked at a number of methods that each of these collections 
have, and in the next chapter, we’ll see that most of those methods are dehned on the 
Sequence protocol. We saw how Swift’s built-in collections allow you to control 
mutability through let and var, and we also saw how to make sense of all the different 
Range types. 
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We saw in the previous chapter that Array, Dictionary, and Set don’t exist in a vacuum. 
They’re ail implemented on top of a rich set of abstractions for processing series of 
elements that’s provided by the Swift standard library. This chapter is all about the 
Sequence and Collection protocols, which form the cornerstones of this model. We’ll 
cover how these protocols work, why they work the way they do, and how you can write 
your own sequences and collections. 


Sequences 

The Sequence protocol stands at the base of the hierarchy. A sequence is a series of 
values of the same type that lets you iterate over the values. The most common way to 
traverse a sequence is a for loop: 

for element in someSequence { 
doSomething(with: element) 

} 

This seemingly simple capability of stepping over elements forms the foundation for a 
large number of useful operations Sequence provides to adopters of the protocol. We 
already mentioned many of them in the previous chapter. Whenever you come up with a 
common operation that depends on sequential access to a series of values, you should 
consider implementing it on top of Sequence, too. We’ll see many examples of how to do 
this throughout this chapter and the rest of the book. 

The requirements for a type to conform to Sequence are fairly small. All it must do is 
provide a makelteratorO method that returns an iterator: 

protocol Sequence { 

associatedtype Iterator: IteratorProtocol 
func makelteratorO -> Iterator 
//... 

} 

The only thing we learn from this (simplified) definition of Sequence is that it’s a type 
that knows how to make an iterator. So let’s first take a closer look at iterators. 


Iterators 


Sequences provide access to their eiements by creating an iterator. The iterator 
produces the values of the sequence one at a time and keeps track of its iteration state as 
it traverses through the sequence. The only method defined in the IteratorProtocol 
protocol is nextO, which must return the next element in the sequence on each 
subsequent call, or nil when the sequence is exhausted: 

protocol IteratorProtocol { 
associatedtype Element 
mutating func nextQ -> Element? 

} 

The associated Element type specifies the type of the values the iterator produces. For 
example, the element type of the iterator for String is Character. By extension, the 
iterator also defines its sequence’s element type. (We’ll talk more about protocols with 
associated types later in this chapter and in the chapter on protocols): 

public protocol Sequence { 
associatedtype Element 
associatedtype Iterator: IteratorProtocol 
where Iterator.Element == Element 


// ... 

} 

You normally only have to care about iterators when you implement one for a custom 
sequence type. Other than that, you rarely need to use iterators directly, because a for 
loop is the idiomatic way to traverse a sequence. In fact, this is what a for loop does 
under the hood: the compiler creates a fresh iterator for the sequence and calls next on 
that iterator repeatedly, until nil is returned. The for loop example we showed above is 
essentially shorthand for the following: 

var iterator = someSequence.makelteratorO 
while let element = iterator.nextQ { 
doSomething(with: element) 

} 

Iterators are single-pass constructs; they can only be advanced, and never reversed or 
reset. While most iterators will produce a finite number of elements and eventually 
return nil from next(), nothing stops you from vending an infinite series that never ends. 


As a matter of fact, the simplest iterator imaginable — short of one that Immediately 
returns nil — is one that just returns the same value over and over again: 

struct Constantiterator: IteratorProtocol { 
typealias Element = Int 
mutatingfunc nextQ -> lnt?{ 
return 1 

} 

} 

The explicit typealias for Element is optional (but often useful for documentation 
purposes, especially in larger protocols). If we omit it, the compiler infers the concrete 
type of Element from the return type of next(): 

struct Constantiterator: IteratorProtocol { 
mutating func nextQ -> lnt?{ 
return 1 

} 

} 

Notice that the nextQ method is declared as mutating. This isn’t strictly necessary in this 
simplistic example because our iterator has no mutable state. In practice, though. 
Iterators are inherently stateful. Almost any useful Iterator requires mutable state to 
keep track of its position in the sequence. 

We can create a new instance of Constantiterator and loop over the sequence it produces 
in a while loop, printing an endless stream of ones: 

var iterator = ConstantIteratorQ 
while let x = iterator.nextQ { 
print(x) 

} 

Let’s look at a more elaborate example. Fibsiterator produces the Fibonacci sequence . It 
keeps track of the current position in the sequence by storing the upcoming two 
numbers. The next method then returns the hrst number and updates the state for the 
following call. Like the previous example, this iterator also produces an “inhnite” 
stream; it keeps generating numbers until it reaches integer overflow, and then the 
program crashes: 


struct Fibsiterator; IteratorProtocol { 



var state = (0,1) 
mutatingfunc nextQ -> lnt?{ 
let upcomingNumber = state. 0 
state = (state. 1, state.0 + state. 1) 
return upcomingNumber 

} 

} 


Conforming to Sequence 

An example of an iterator that produces a finite sequence is the following Prefixiterator, 
which generates all prefixes of a string (including the string itself). It starts at the 
beginning of the string, and with each call of next, increments the slice of the string it 
returns by one character until it reaches the end: 

struct Prefixiterator: IteratorProtocoi { 
let string: String 
var offset: String.Index 

init(string: String) { 
self.string = string 
offset = string.startindex 

} 

mutating func nextQ -> Substring? { 
guard offset < string.endindex else { return nil} 
offset = string.index(after: offset) 
return string!..<offset] 

} 

} 

(string!..<offset] is a slicing operation that returns the substring between the start and 
the offset — we saw the partial range notation in the previous chapter, and we’ll talk 
more about slicing later.) 

With Prefixiterator in place, defining the accompanying PrefixSequence type is easy. 
Again, it isn’t necessary to specify the associated Iterator or Element types explicitly 
because the compiler can infer them from the return type of the makelterator method: 


struct PrefixSequence: Sequence { 


let string: String 

func makelteratorO -> Prefixiterator { 
return Prefixlterator(string: string) 

} 

} 

Now we can use a for loop to iterate over all the prefixes: 

for prefix in PrefixSequence(string: "Hello") { 
print(prefix) 

} 

/* 

H 

He 

Hel 

Hell 

Hello 

*/ 


Or we can perform any other operation provided by Sequence: 

PrefixSequence(string: "Hello"). map {$0.uppercased()} 

//["H", "HE", ''HEL” "HELL", "HELLO"} 

We can create sequences for Constantiterator and Fibsiterator in the same way. We’re not 
showing them here, but you may want to try this yourself. Just keep in mind that these 
iterators create infinite sequences. Use a construct like for i in fibsSequence.prefix(IO) to 
slice off a finite piece. 


Iterators and Value Semantics 

The iterators we’ve seen thus far all have value semantics. If you make a copy of one, the 
iterator’s entire state will be copied, and the two Instances will behave independently of 
one other, as you’d expect. Most iterators in the standard library also have value 
semantics, but there are exceptions. 

To illustrate the difference between value and reference semantics, we first take a look at 
StrideTolterator. It’s the underlying iterator for the sequence that’s returned from the 


stride(from:to:by:) function. Let’s create a StrideTolterator and call next a couple of 
times: 

//A sequence from Qto9 

let seq = stride(from: 0, to: 10, by: 1) 

var i1 = seq.makelteratorQ 

'll .nextO //Optional(O) 

iT .nextO //Optional(l) 

i1 Is now ready to return 2. Now, say you make a copy of It: 
var i2 = i1 

Both the original and the copy are now separate and Independent, and both return 2 
when you call next: 

iT .nextO //Optional(2) 
iT .nextQ //Optional(3) 
i2.nextQ //Optional(2) 

\2.next{) //Optional(3) 

This Is because StrideTolterator, a pretty simple struct whose Implementation Is not too 
dissimilar from our Fibonacci Iterator above, has value semantics. 

Now let’s look at an Iterator that doesn’t have value semantics. Anylterator Is an Iterator 
that wraps another Iterator, thus “erasing” the base Iterator’s concrete type. An example 
where this might be useful Is If you want to hide the concrete type of a complex Iterator 
that would expose Implementation details In your public API. The way Anylterator does 
this Is by wrapping the base Iterator In an Internal box object, which Is a reference type. 
(If you want to learn exactly how this works, check out the section on type erasure In the 
protocols chapter.) 

To see why this Is relevant, we create an Anylterator that wraps 11, and then we make a 
copy: 

var 13 = Anylterator(il) 
var 14 = 13 


In this situation, original and copy aren’t Independent because, despite being a struct, 
Anylterator doesn’t have value semantics. The box object Anylterator uses to store Its 
base Iterator Is a class Instance, and when we assigned 13 to 14, only the reference to the 


box got copied. The storage of the box is shared between the two iterators. Any caiis to 
next on either i3 or i4 now increment the same underiying iterator: 

]3.nextO //0ptional(4) 
i4.nextO //0ptional(5) 
i3.nextO //0ptional(6) 
i3.nextO //0ptional(7) 

Obviousiy this couid lead to hugs, although in all likelihood, you’ll rarely encounter this 
particular problem in practice. Iterators are usually not something you pass around in 
your code. You’re much more likely to create one locally — sometimes explicitly, but 
mostly implicitly through a for loop — use it once to loop over the elements, and then 
throw it away. If you hnd yourself sharing iterators with other objects, consider 
wrapping the iterator in a sequence instead. 


Function-Based Iterators and Sequences 

Anylterator has a second initializer that takes the next function directly as its argument. 
Together with the corresponding AnySequence type, this allows us to create iterators 
and sequences without defining any new types. For example, we could’ve defined the 
Fibonacci iterator alternatively as a function that returns an Anylterator: 

func fibsIteratorO -> Anylterator<lnt> { 
var state = (0,1) 
return Anylterator { 
let upcomingNumber = state.0 
state = (state. 1, state.0 + state. 1) 
return upcomingNumber 

} 

} 

By keeping the state variable outside of the iterator’s next closure and capturing it inside 
the closure, the closure can mutate the state every time it’s invoked. There’s only one 
functional difference between the two Fibonacci iterators: the definition using a custom 
struct has value semantics, and the definition using Anylterator doesn’t. 

Creating a sequence out of this is even easier now because AnySequence provides an 
initializer that takes a function, which in turn produces an iterator: 

let fibsSequence = AnySequence(fibslterator) 


Array(fibsSequence.prefix(10))/^fO, 7, 1,2,3, 5, 8, 13,21,34] 


Another alternative is to use the sequence function, which has two variants. The first, 
sequence(first:next:), returns a sequence whose first element is the first argument you 
passed in; subsequent elements are produced by the closure passed in the next 
argument. The other variant, sequence(state:next:), is even more powerful because it 
can keep some arbitrary mutable state around between invocations of the next closure. 
We can use this to build the Fibonacci sequence with a single function call: 

let fibsSequence2 = sequence(state: (0,1)) { 

//The compiler needs a little type inference help here 
(state: inout (Int, Int)) -> Int? in 
let upcomingNumber = state.0 
state = (state. 1, state.0 + state. 1) 
return upcomingNumber 

} 

Array(fibsSequence2.prefix(10))/^f0, 1, 1,2, 3,5,8, 13,21,34] 


The return type of sequence(first:next:) and sequence(state:next:) is 
UnfoldSequence. This term comes from functional programming, where the 
same operation is often called unfold, sequence is the natural counterpart to 
reduce (which is often called fold in functional languages). Where reduce 
reduces {or folds) a sequence into a single return value, sequence unfolds a 
single value to generate a sequence. 


The two sequence functions are extremely versatile. They’re often a good fit for 
replacing a traditional C-style for loop that uses non-linear math. In the chapter on 
structs and classes, we’ll talk more about inout parameters. 


Infinite Sequences 

Like all iterators we’ve seen so far, the sequence functions apply their next closures 
lazily, i.e. the next value isn’t computed until it’s requested by the caller. This makes 
constructs like fibsSequence2.prefix(10) work. prefix(10) only asks the sequence for its 
first (up to) 10 elements and then stops. If the sequence had tried to compute all its 
values eagerly, the program would’ve crashed with an integer overflow before the next 
step had a chance to run. 



The possibility of creating infinite sequences is one thing that sets sequences apart from 
collections, which can’t be inhnite. 


Unstable Sequences 

Sequences aren’t limited to classic collection data structures, such as arrays or lists. 
Network streams. Hies on disk, streams of UI events, and many other kinds of data can 
all be modeled as sequences. But not all of these behave like an array when you iterate 
over the elements more than once. 

While the Fibonacci sequence isn’t affected by a traversal of its elements (and a 
subsequent traversal starts again at zero), a sequence that represents a stream of 
network packets is consumed by the traversal; it won’t produce the same values again if 
you do another iteration. Both are valid sequences, though, so the documentation is 
v ery clear that Sequence makes no guarantee about multiple traversals: 


The Sequence protocol makes no requirement on conforming types regarding 
whether they will be destructively consumed by iteration. As a consequence, 
don’t assume that multiple for-in loops on a sequence will either resume 
iteration or restart from the beginning: 

for element in sequence { 
if ... some condition { break} 

} 

for element in sequence { 

// No defined behavior 

} 


A conforming sequence that is not a collection is allowed to produce an 
arbitrary sequence of elements in the second for-in loop. 


This also explains why the seemingly trivial first property is only available on 
collections, and not on sequences. Invoking a property getter ought to be 
non-destructive, and only the Collection protocol guarantees safe multi-pass iteration. 





As an example of a destructively consumed sequence, consider this wrapper on the 
read Line function, which reads lines from the standard input: 

let standardin = AnySequence { 
return Anylterator { 
readLineQ 

} 

} 

Nowyou can use this sequence with the various extensions of Sequence. For example, 
you could write a line-numbering version of the Unix cat utility: 

let numberedStdIn = standardin.enumeratedO 
for (i, line) in numberedStdIn { 
print("\(i-l-1):\(line)'') 

} 

The enumerated method wraps a sequence in a new sequence that produces pairs of the 
original sequence’s elements and incrementing numbers starting at zero. Just like our 
wrapper of readLine, elements are lazily generated. The consumption of the base 
sequence only happens when you move through the enumerated sequence using its 
iterator, and not when it’s created. So if you run the above code from the command line, 
you’ll see it waiting inside the for loop. It prints the lines you type in as you hit return; it 
does not wait until the input is terminated with control-D. But nonetheless, each time 
enumerated serves up aline from standardin, it’s consuming the standard input. You 
can’t iterate over it twice to get the same results. 

As an author of a Sequence extension, you don’t need to take into account whether or 
not the sequence is destructively consumed by iteration. But as a caller of a method on a 
sequence type, you should keep it in mind. 

A certain sign that a sequence is stable is if it also conforms to Collection because this 
protocol makes that guarantee. The reverse isn’t true. Even the standard library has 
some sequences that can be traversed safely multiple times although they aren’t 
collections. Examples include the StrideTo and StrideThrough types, as returned by 
stride(from:to:by:) and stride(from:through:by:). The fact that you can stride over 
floating-point numbers would make it tricky (though probably not impossible) to render 
them as a collection, so they’re just sequences. 


The Relationship Between Sequences and Iterators 


Sequences and Iterators are so similar that you may wonder why these need to be 
separate types at all. Can’t we just fold the IteratorProtocol functionality into Sequence? 
This would indeed work fine for destructively consumed sequences, like our standard 
input example. Sequences of this kind carry their own iteration state and are mutated as 
they’re traversed. 

Stable sequences, like arrays or our Fibonacci sequence, must not be mutated by a for 
loop: they require separate traversal state, and that’s what the iterator provides (along 
with the traversal logic, but that might as well live in the sequence). The purpose of the 
makelterator method is to create this traversal state. 

Every Iterator can also be seen as an unstable sequence over the elements it has yet to 
return. As a matter of fact, you can turn every iterator into a sequence simply by 
declaring conformance; Sequence comes with a default implementation for 
makelterator that returns self if the conforming type is an iterator. Jordan Rose, a 
member of the Swift team, said via the swift-evolution mailing list that IteratorProtocol 
would actually inherit from Sequence if it weren’t for language limitations (namely, lack 
of support for recursive associated type constraints). 

Though it may not currently be possible to enforce this relationship, most iterators in 
the standard library do conform to Sequence. 


Subsequences 

Sequence has another associated type, named Subsequence; 

protocol Sequence { 
associatedtype Element 
associatedtype Iterator: IteratorProtocol 
where Iterator.Element == Element 
associatedtype Subsequence 
//... 

} 

Subsequence is used as the return type for operations that return slices of the original 

sequence: 

^ prefix and suffix — take the first or last n elements 



^ prefix(while:) — take elements from the start as long as they conform to a 
condition 

^ dropFirst and dropLast — return subsequences where the first or last n elements 
have been removed 

^ drop(whUe:) — drop elements until the condition ceases to be true, and then 
return the rest 

-> split — break up the sequence at the specified separator elements and return an 
array of subsequences 

If you don’t specify a type for Subsequence, the compiler will infer it to be 
AnySequence<Element> because Sequence provides default implementations for the 
above methods with that return type. If you want to use your own subsequence type, 
you must provide custom implementations for these methods. 

It can sometimes be convenient if Subsequence == Self, i.e. if subsequences have the 
same type as the base sequence, because this allows you to pass a slice everywhere the 
base collection is expected. The standard library collections have separate slice types, 
however; the main motivation for this is to avoid accidental memory “leaks” that can be 
caused by a tiny slice that keeps its base collection (which may be very large) alive much 
longer than anticipated. Making slices their own types makes it easier to bind their 
lifetimes to local scopes. 

In an ideal world, the associated type declaration would include constraints to ensure 
that Subsequence (a) is also a sequence, and (b) has the same element and subsequence 
types as its base sequence. It should look something like this: 

associatedtype Subsequence: Sequence 
where Element == Subsequence.Element, 

Subsequence.Subsequence == Subsequence 

This didn’t make it into Swift 4.0 because the compiler lacks support for recursive 
protocol constraints (Sequence would reference itself). However, we expect these in a 
future Swift release. Until then, you may find yourself having to add some or all of these 
constraints to your own Sequence extensions to help the compiler understand the types. 
The standard library was designed from the start with recursive constraints in mind; 
many Sequence and Collection APIs will be easier to understand once this feature is 
implemented because they’ll be able to drop the explicit constraints that are currently 
still necessary. 


The following example checks if a sequence starts with the same n elements from the 
head and the tail. It does this by comparing the sequence’s prefix with the reversed 
suffix: 

extension Sequence where Element: Equatabie, Subsequence: Sequence, 

Subsequence.Element == Element 

{ 

func headMirrorsTailL n: Int) -> Bool { 
let head = prefix(n) 
let tail = suffix(n).reversed() 
return head.elementsEqual(tail) 

} 

} 

[1,2,3,4,2,1]. head MirrorsTai 1(2) true 

The comparison using elementsEqual only passes type checking if we tell the compiler 
that the subsequence is also a sequence, and that its elements have the same type as the 
base sequence’s elements (which we constrained to Equatabie). 

We show another example of sequence extensions like this in the chapter on generics. 


A Linked List 

As an example of a custom sequence, let’s implement one of the most basic data 
structures of all: a singly linked list, defined using indirect enums. A linked list node is 
one of either two things: a node with a value and a reference to the next node, or a node 
indicating the end of the list. We can define it like this: 

/// J\ singly linked list 
enum List<Element> { 
case end 

indirect case node(Element, next: List<Element>) 

} 

The indirect keyword here indicates that the compiler should represent the node value as 
a reference. Swift enums are value types. This means they hold their values directly in 
the variable, rather than the variable holding a reference to the location of the value. 

This has many benefits, as we’ll see in the structs and classes chapter. But value types 
can’t refer to themselves recursively because doing so would make it impossible for the 


compiler to calculate their size. The indirect keyword allows an enum case to be held as 
a reference and thus allows the enum to hold a reference to itself. 

We prepend an element to a list by creating a new node, with the next: value set to the 
current node: 

let emptyList = List<lnt>.end 

let oneElementList = List.node(1, next: emptyList) 

// node(l, next: List<Swift.lnt>.end) 

We can create a method for prepending to make this process a little easier. We name this 
method cons, because that’s the name of the operation in LISP (it’s short for “construct,” 
and adding elements onto the front of the list is sometimes called “consing”): 

extension List { 

/// Return a new list by prepending a node with value x' to the 
///front of a list. 

func cons(_ x: Element) -> List { 
return .node(x, next: self) 

} 

} 

//A 3-element list, of (3 2 7) 

let list = List<int>.end.cons(1).cons(2).cons(3) 

/* 

node(3, next: List<Swift.lnt>.node(2, next: List<Swift.lnt>.node(l, 
next: List<Swift.lnt>.end))) 

*/ 


The chaining syntax makes it clear how a list is constructed, but it’s also kind of ugly. We 
can add conformance to ExpressibleByArrayLiteral to be able to initialize a list with an 
array literal. The implementation first reverses the input array (because lists are built 
from the end) and then uses reduce to prepend the elements to the list one by one, 
starting with the .end node: 

extension List: ExpressibleByArrayLiteral! 
init(arrayLiteral elements: Element...) { 
self = elements.reversed().reduce(.end) { partialList, element in 
partialList.cons(element) 

} 

} 


} 


let list2: List = [3,2,1] 

/* 

node(3, next: List<Swift.lnt>.node(2, next: List<Swift.lnt>.node(l, 
next: List<Swift.lnt>.end))) 

*/ 


This list type has an interesting property: it’s “persistent .” The nodes are immutable — 
once created, you can’t change them. Consing another element onto the list doesn’t 
copy the list; it just gives you a new node that links onto the front of the existing list. 

This means two lists can share a tail: 


letx = l.cons(3) 


next 


let I = List<lnt>.end.cons(1).cons(2) 


let y = l.cons(33) ^ 


2 

next 

-► 

1 

next 

-► 

.end 


33 


next 


Figure 3.1; List Sharing 


The Immutability of the list is key here. If you could change the list (say, remove the last 
entry, or update the element held in a node), then this sharing would be a problem — x 
might change the list, and the change would affect y. 

Still, we can define mutating methods on List to push and pop elements (because the list 
is also a stack, with consing as push and unwrapping the next element as pop): 

extension List { 

mutating func push(_x: Element) { 
self = self.cons(x) 

} 












mutating func popO -> Element? { 
switch self { 
case .end: return nil 
case let .node(x, next: tail): 
self = tail 
return x 

} 

} 


But didn’t we just say that the list had to be Immutable for the persistence to work? How 
can it have mutating methods? 

These mutating methods don’t change the list. Instead, they just change the part of the 
list the variables refer to: 

var stack: List<lnt> = [3,2,1] 
var a = stack 
var b = stack 

a.popO // Optional(3) 
a.popO // Optional(2) 

a. popO // Optional( 1) 

stack.popO // Optional(3) 
stack.push(4) 

b. popO Opt/ona/f3j 
h.popO // Optional(2) 
b.popO // Optional(l) 

stack.popO // 0ptional(4) 
stack.popO //Optional(2) 
stack.popO// Optionat(l) 

This shows us the difference between values and variables. The nodes of the list are 
values; they can’t change. A node of three and a reference to the next node can’t become 
some other value; it’ll be that value forever, just like the number three can’t change. It 
just is. Just because these values in question are structures with references to each other 
doesn’t make them less value-like. 


A variable a, on the other hand, can change the value it holds. It can be set to hold a 
value of an indirect reference to any of the nodes or to the value end. But changing a 
doesn’t change these nodes; it just changes which node a refers to. 


This is what these mutating methods on structs do — they take an implicit inout 
argument of self, and they can change the value self holds. This doesn’t change the list, 
but rather which part of the list the variable currently represents. In this sense, through 
indirect, the variables have become iterators into the list: 


let a = List<lnt>.end.cons(1).cons(2).cons(3) 



I has value 

var b = 1 


a 



b.popO 


Figure 3.2: List Iteration 















You can, of course, declare your variables with let instead of var, in which case the 
variables will be constant (i.e. you can’t change the value they hold once they’re set). But 
let is about the variables, not the values. Values are constant by dehnition. 

Now this is all just a logical model of how things work. In reality, the nodes are actually 
places in memory that point to each other. And they take up space, which we want hack 
if it’s no longer needed. Swift uses automated reference counting (ARC) to manage this 
and frees the memory for the nodes that are no longer used: 


This node has no more 
variables referring to it 


a.popO 

I now has value 


3 

next 

-► 

2 

next 

-► 

1 

next 

-► 

.end 


... so its memory can \ has value 

be reclaimed 


Figure 3.3: List Memory Management 


We’ll discuss inout in more detail in the chapter on functions, and we’ll cover mutating 
methods as well as ARC in the structs and classes chapter. 


Conforming List to Sequence 

Since list variables are Iterators into the list, this means you can use them to conform 
List to Sequence. As a matter of fact. List is an example of an unstable sequence that 
carries its own iteration state, like we saw when we talked about the relationship 
between sequences and iterators. We can add conformance to IteratorProtocol and 
Sequence in one go just by providing a nextO method; the implementation of this is 
exactly the same as for pop: 

extension List: IteratorProtocol, Sequence { 
mutatingfunc nextQ -> Element?! 
return popQ 

} 

} 










Now you can use lists with fo r... i n: 


let list: List = ["1", "2", "3”] 
for X in list{ 

print("\(x) ", terminator: "") 

}//1 2 3 

This also means that, through the power of protocol extensions, we can use List with 
dozens of standard library functions: 

iist.joined(separator: //1,2,3 
list.contains("2") /'true 
iist.fiatMap {int($0)} //[1,2, 3] 
iist.eiementsEquai(["1 ", "2", "3"]) //true 


In computer science theory, linked lists are more efficient than arrays for some 
common operations. In practice, however, it’s really hard to outperform arrays 
on modern computer architectures with their extremely fast caches and 
(relatively) slow main memory. Because arrays use contiguous memory for 
their elements, the processor can process them way more efficiently. For a 
good overview of collection performance in Swift, see Karoly Lorentey’s book 
Optimizins Collections . 


Collections 


A collection is a stable sequence that can be traversed nondestructively multiple times. 
In addition to linear traversal, a collection’s elements can also be accessed via subscript 
with an index. Subscript indices are often integers, as they are in arrays. But as we’ll see, 
indices can also be opaque values (as in dictionaries or strings), which sometimes makes 
working with them non-intuitive. A collection’s indices invariably form a finite range, 
with a defined start and end. This means that unlike sequences, collections can’t be 
infinite. 

The Collection protocol builds on top of Sequence. In addition to all the methods 
inherited from Sequence, collections gain new capabilities that either depend on 
accessing elements at specific positions or rely on the guarantee of stable iteration, like 
the count property (if counting the elements of an unstable sequence consumed the 
sequence, it would kind of defeat the purpose). 




Even if you don’t need the special features of a collection, you can use Collection 
conformance to signal to users that your own sequence type is finite and supports 
multi-pass iteration. It’s somewhat strange that you have to come up with an index if all 
you want is to document that your sequence is multi-pass. Picking a suitable index type 
to represent positions in the collection is often the hardest part of implementing the 
Collection protocol. One reason for this design is that the Swift team wanted to avoid the 
potential confusion of having a distinct protocol for multi-pass sequences that had 
requirements identical to Sequence but different semantics. 

Collections are used extensively throughout the standard library. In addition to Array, 
Dictionary, and Set, String and its views are all collections, as are CountableRange and 
UnsafeBufferPointer. Increasingly, we’re also seeing types outside the standard library 
adopt the Collection protocol. Two examples of Foundation types that gained a ton of 
new capabilities in this way are Data and IndexSet. 


A Custom Collection 

To demonstrate how collections in Swift work, we’ll implement one of our own. Probably 
the most useful container type not present in the Swift standard library is a queue. Swift 
arrays are able to easily be used as stacks, with append to push and popLast to pop. 
However, they’re not ideal to use as queues. You could use push combined with 
removefat: 0), but removing anything other than the last element of an array is an 0(n) 
operation — because arrays are held in contiguous memory, every element has to shuffle 
down to fill the gap (unlike popping the last element, which can be done in constant 
time). 


Designing a Protocol for Queues 

Before we implement a queue, maybe we should define what we mean by it. A good way 
to do this is to define a protocol that describes what a queue is. Let’s try the following 
definition: 

/// J\ type that can 'enqueue' and 'dequeue' elements. 
protocol Queue { 

///The type of elements held in 'self. 

associatedtype Element 

///Enqueue 'element'to 'self. 

mutating func enqueue(_ newElement: Element) 

///Dequeue an element from 'self. 



mutatingfunc dequeueO -> Element? 

} 

As simple as this is, it says a lot about what our definition of queue is: it’s defined 
generically. It can contain any type, represented by the associated type Element. It 
imposes no restrictions on what Element is. 

It’s important to note that the comments above the methods are as much a part of a 
protocol as the actual method names and types. Here, what we don’t say tells us as much 
as what we do: there’s no guarantee of the complexity of enqueue or dequeue. We 
could’ve said, for example, that both should operate in constant (0(1)) time. This would 
give users adopting this protocol a good idea of the performance characteristics of any 
kind of queue implementing this protocol. But it would rule out data structures, such as 
priority queues, that might have an 0(iog„) enqueueing operation. 

It also doesn’t offer a peek operation to check without dequeuing, which means it could 
be used to represent a queue that doesn’t have such a feature (such as, say, a queue 
interface over an operating system or networking call that could only pop, not peek). It 
doesn’t specify whether the two operations are thread-safe. It doesn’t specify that the 
queue is a Collection (though the implementation we’re about to write will be). 

It doesn’t even specify that it’s a FIFO queue — it could be a LIFO queue, and we could 
conform Array to it, with append for enqueue and dequeue implemented via 
isEmpty/popLast. 

Speaking of which, here is something the protocol specifies: like Array’s popLast, 
dequeue returns an optional. If the queue is empty, it returns nil. Otherwise, it removes 
and returns the last element. We don’t provide an equivalent for Array.removeLast, 
which traps if you call it on an empty array. 

By making dequeue an optional, the most common operation of repeatedly dequeuing 
an element until the queue is empty becomes a one-liner, along with the safety of not 
being able to get it wrong: 

while let x = queue.dequeueO { 

//Process queue element 

} 

The downside is the inconvenience of always having to unwrap, even when you already 
know the queue can’t be empty. The right tradeoff for your particular data type depends 
on how you envision it to be used. (Conforming your custom collection to the Collection 


protocol gives you both variants for free, anyway, since Collection provides both a 
popFirst and a removeFirst method.) 


A Queue Implementation 

Now that we’ve defined what a queue is, iet’s impiement it. Beiow is a very simpie FIFO 
queue, with just enqueue and dequeue methods implemented on top of a couple of 
arrays. 

Since we’ve named our queue’s generic placeholder Element, the same name as the 
required associated type, there’s no need to define it. It’s not necessary to name it 
Element though — the placeholder is just an arbitrary name of your choosing. If it were 
named Foo, you could either define typealias Element = Foo, or leave Swift to infer it 
implicitly from the return types of the enqueue and dequeue implementations: 

///An efficient variable-size FIFO queue of elements of type 'Element' 
struct FIFOQueue<Element>: Queue { 
private var left: [Element] = [] 
private var right: [Element] = [] 

///Add an element to the back of the queue. 

/// - Complexity: 0( 7 ). 

mutating func enqueue(_ newElement: Element) { 
right.append(newElement) 

} 

/// Removes front of the queue. 

///Returns 'nil' in case of an empty queue. 

/// - Complexity: Amortized 0(1). 
mutating func dequeueO -> Element? { 
if left.isEmpty { 
left = right.reversedO 
right.removeAllQ 

} 

return left.popLastQ 

} 

} 

This implementation uses a technique of simulating a queue through the use of two 
stacks (two regular arrays). As elements are enqueued, they’re pushed onto the “right” 


stack. Then, when elements are dequeued, they’re popped off the “left” stack, where 
they’re held In reverse order. When the left stack Is empty, the right stack is reversed 
onto the left stack. 

You might And the claim that the dequeue operation is 0(1) slightly surprising. Surely it 
contains a reverse call that is 0(n)? But while this is true, the overall amortized time to 
pop an item is constant — over a large number of pushes and pops, the time taken for 
them all is constant, even though the time for individual pushes or pops might not be. 

The key to why this is lies in understanding how often the reverse happens and on how 
many elements. One technique to analyze this is the “banker’s methodology.” Imagine 
that each time you put an element on the queue, you pay a token into the bank. Single 
enqueue, single token, so constant cost. Then when it comes time to reverse the 
right-hand stack onto the left-hand one, you have a token in the bank for every element 
enqueued, and you use those tokens to pay for the reversal. The account never goes into 
debit, so you never spend more than you paid. 

This kind of reasoning is good for explaining why the “amortized” cost of an operation 
over time is constant, even though individual calls might not be. The same kind of 
justification can be used to explain why appending an element to an array in Swift is a 
constant time operation. When the array runs out of storage, it needs to allocate bigger 
storage and copy all its existing elements into it. But since the storage size doubles with 
each reallocation, you can use the same “append an element, pay a token, double the 
array size, spend all the tokens but no more” argument. 


Conforming to Collection 

We now have a container that can enqueue and dequeue elements. The next step is to 
add Collection conformance to FIFOQueue. Unfortunately, figuring out the minimum set 
of implementations you must provide to conform to a protocol can sometimes be a 
frustrating exercise in Swift. 

At the time of writing, the Collection protocol has a whopping six associated types, four 
properties, seven instance methods, and two subscripts: 

protocol Collection; Sequence { 
associatedtype Element///nfiented from Sequence 
associatedtype Index: Comparable 


associatedtype IndexDistance: Signedinteger = Int 



associatedtype Iterator: IteratorProtocol = lndexinglterator<Self> 
where Iterator.Element == Element 
associatedtype Subsequence: Sequence 
/*... */ 

associatedtype Indices: Sequence = Defaultlndices<Self> 

/*... */ 

var first: Element? {get} 
var indices: Indices { get } 
var isEmpty: Bool { get } 
var count: IndexDistance { get } 

func makelteratorO -> Iterator 

func prefix(through: Index) -> Subsequence 

func prefix(upTo: Index) -> Subsequence 

func suffix(from: Index) -> Subsequence 

func distance(from: Index, to: Index) -> IndexDistance 

func index(_: Index, offsetBy: IndexDistance) -> Index 

func index(_: Index, offsetBy: IndexDistance, limitedBy: Index) -> Index? 

subscript(position: Index) -> Element { get} 
subscript(bounds: Range<lndex>) -> Subsequence {get} 

} 

(Note that this Is an idealized view of the protocol. In Swift 4.0, some of these 
requirements are really defined on two hidden protocols named _lndexable and 
_lndexableBase, which Collection extends. This construction is a workaround for the 
lack of support for recursive associated type constraints in the compiler that was already 
fixed in the post-4.0 master branch. Swift 4.1 will no longer require this stopgap 
measure, and the hidden protocols will be merged into Collection.) 

The associated Subsequence type, which is inherited from Sequence, has the following 
additional constraints (because we’re inside Collection, the reference to Sequence isn’t 
recursive anymore; ideally, the subsequence of a collection should also be a Collection, 
but that would require support for recursive constraints): 

associatedtype Subsequence: Sequence 
where Element == Subsequence.Element, 

Subsequence == Subsequence.Subsequence 



The Indices type also has a number of constraints. The most Important one connects 
Index with Indices, specifying that the former is the element type of the latter. The other 
constraints say that Indices is its own subsequence: 

associatedtype Indices: Sequence = Defaultlndices<Self> 
where Index == Indices.Element, 

Indices == Indices.Subsequence, 

Indices.Element == Indices.Index, 

Indices.Index == Subsequence.Index 

With all the requirements above, conforming to Collection seems like a daunting task. 
Well, it turns out it’s actually not that bad. Notice that all associated types except I ndex 
and Element have default values, so you don’t need to care about those unless your type 
has special requirements. The same is true for most of the functions, properties, and 
subscripts: protocol extensions on Collection provide the default implementations. 

Some of these extensions have associated type constraints that match the protocol’s 
default associated types; for example. Collection only provides a default implementation 
of the makelterator method if its Iterator is an lndexinglterator<Self>: 

extension Collection where Iterator == lndexinglterator<Self> { 

///Returns an iterator over the elements of the collection. 
func makelteratorO -> lndexinglterator<Self> 

} 

If you decide that your type should have a different iterator type, you’d have to 
implement this method. 

Working out what’s required and what’s provided through defaults isn’t exactly hard, but 
it’s a lot of manual work, and unless you’re very careful not to overlook anything, it’s 
easy to end up in an annoying guessing game with the compiler. The most frustrating 
part of the process may be that the compiler has all the information to guide you; the 
diagnostics just aren’t helpful enough yet. 

For the time being, your best hope is to find the minimal conformance requirements 
spelled out in the documentation, as is in fact the case for Collection: 


... To add Collection conformance to your type, you must declare at least the 
following requirements: 


^ The startindex and endindex properties 

^ A subscript that provides at least read-only access to your type’s 
elements 

^ The index(after:) method for advancing an index into your collection 


So in the end, we end up with these requirements: 

protocol Collection; Sequence { 

///A type that represents a position in the collection. 
associatedtype Index: Comparable 

///The position of the first element in a nonempty collection. 
var startindex: Index { get } 

///The collection's "past the end" position—that is, the position one 
///greater than the last valid subscript argument. 
var endindex: Index { get } 

/// Returns the position immediately after the given index. 
func index(after I: Index) -> Index 
///Accesses the element at the specified position. 
subscript(position: Index) -> Element { get} 

} 

We can conform FIFOQueue to Collection like so: 

extension FIFOQueue:Collection { 
public var startindex: Int { return 0} 
public var endindex: Int { return left.count -t right.count} 

public func index(after I: Int) -> Int { 
precondition(i < endindex) 

return I -i-1 

} 

public subscript(position: Int) -> Element { 
precondition((0..<endlndex).contains(position), "Index out of bounds") 
if position < left.endindex { 
return left[left.count - position - 1] 

} else { 

return right[position - left.count] 

} 



} 

} 

We use Int as our queue’s Index type. We don’t specify an explicit typealias for the 
associated type; just like with Element, Swift can infer it from the method and property 
definitions. Note that since the indexing returns elements from the front first, 

Queue.fi rst returns the next item that will be dequeued (so it serves as a kind of peek). 

With just a handful of lines, queues now have more than 40 methods and properties at 
their disposal. We can iterate over queues: 

varq = FIFOQueue<String>() 
forxin["1'', "2", "foo","3"]{ 
q.enqueue(x) 

} 

fors in q { 

print(s, terminator: " ") 

]//1 2 foo 3 

We can pass queues to methods that take sequences: 

var a = Array(q) // f"T', "2", "foo", "3"] 
a.append(contentsOf: q[2...3]) 
a //f"1", "2", "foo", "3", "foo", "3"] 

We can call methods and properties that extend Sequence: 

q.map {$0.uppercased() }//r'7" "2", "FOO", "3"] 
q.flatMap {lnt($0)} //[1,2, 3] 
q.filter {$0.count > 1 } // ["foo"] 
q.sortedO // ["1", "2", "3", "foo"] 
q.joined(separator: " ")// 1 2 foo 3 

And we can call methods and properties that extend Collection: 

q.isEmpty/^folse 
q.count//4 
q .f i rst // Optional(" 7 ") 


Conforming to ExpressibleByArrayLiteral 


When writing a coliection iike this, it’s nice to impiement ExpressibleByArrayLiteral too, 
as we did with our linked iist type. This will allow users to create a queue using the 
famiiiar [valuel, value2, etc] syntax. This can be done easily, like so: 

extension FIFOQueue: ExpressibleByArrayLiteral { 
public init(arrayLiteral elements: Element...) { 
left = elements.reversedQ 
right = [] 

} 

} 

For our queue logic, we want to reverse the eiements to have them ready for use on the 
ieft-hand buffer. Of course, we couid just copy the eiements to the right-hand buffer, but 
since we’re going to be copying elements anyway, it’s more efficient to copy them in 
reverse order so that they don’t need reversing iater when they’re dequeued. 

Now queues can easiiy be created from iiterais: 

let queue: FIFOQueue = ,2,3] //FIFOQueue<lnt>(left: [3,2, 1], right: []) 


Literals 

It’s important to underiine the difference between literals and types in Swift here. [1,2,3] 
is not an array. Rather, it’s an array literal — something that can be used to create any 
type that conforms to ExpressibleByArrayLiteral. This particuiar iiterai contains other 
iiterais — integer iiterais — which can create any type that conforms to 
ExpressibleBylntegerLiteral. 

These iiterais have “defauit” types — types that Swift wiil assume if you don’t specify an 
explicit type when you use a iiterai. So array iiterais default to Array, integer iiterais 
default to Int, float literals default to Double, and string literals default to String. But this 
only occurs in the absence of you specifying otherwise. For example, the queue declared 
above is a queue of integers, but it could’ve been a queue of some other integer type: 

let byteQueue: FlF0Queue<Ulnt8> = [1,2,3] 

// FlF0Queue<Ulnt8>(left: [3,2, 1], right: []) 


Often, the type of the literal can be inferred from the context. For example, this is what it 
looks like if a function takes a type that can be created from literals: 

func takesSetOfFloats(floats: Set<Float>) { 

} 

takesSetOfFloats(floats: [1,2,3]) 

This literal will be interpreted as Set<Float>, not as Array<lnt>. 


Associated Types 

We’ve seen that Collection provides defaults for all but two of its associated types; types 
adopting the protocol only have to specify an Element and an Index type. While you 
don’t have to care much about the other associated types, it’s a good idea to take a brief 
look at each of them in order to better understand what their specific purposes are. Let’s 
go through them one by one. 

Iterator. Inherited from Sequence. We already looked at iterators in detail in our 
discussion on sequences. The default iterator type for collections is 
lndexinglterator<Self>. This is a simple struct that wraps the collection and uses the 
collection’s own indices to step over each element. The implementation looks like this: 

public struct lndexinglterator<Elements: _lndexableBase> 

: IteratorProtocol, Sequence 

{ 

internal let _elements: Elements 

internal var _position: Elements.Index 

init{_elements: Elements) { 
self._elements = _elements 
self._pcsiticn = _elements.startlndex 

} 

public mutating func nextQ -> Elements.Element? { 
if -pcsiticn == _elements.end Index { return nil } 
let element = _elements[_pcsiticn] 

_elements.fcrmlndex(after: &_pcsiticn) 



return element 


} 

} 

(The generic constraint <Elements: _lndexableBase> shouid reaily be 

<Elements: CoUection> once the compiler allows recursive associated type constraints.) 

Most collections in the standard library use Indexingiterator as their iterator. There 
should be little reason to write your own iterator type for a custom collection. 

Subsequence. Also inherited from Sequence, but Collection restates this type with 
tighter constraints. A collection’s Subsequence should itself also be a Collection. (We say 
“should” rather than “must” because this requirement is currently not fully expressible 
in the type system.) The default is Slice<Self>, which wraps the original collection and 
stores the slice’s start and end index in terms of the base collection. 

It can make sense for a collection to customize its Subsequence type, especially if it can 
be Self (i.e. a slice of the collection has the same type as the collection itself). 
Foundation’s Data is an example of a such collection. We’ll talk more about slicing later 
in this chapter. 

IndexDistance. A signed integer type that represents the number of steps between two 
indices. Setting this to anything other than the default Int is rarely necessary. An 
example where it makes sense to change IndexDistance to (say) Int64 is a collection for 
accessing flies that has to work with very large flies (> 4 GB) on 32-bit systems. 

Indices. The return type of the collection’s indices property. It represents a collection 
containing all indices that are valid for subscripting the base collection, in ascending 
order. Note that the endindex is not included because it signifies the “past the end” 
position and thus is not a valid subscript argument. 

The default type is the imaginatively named Defaultlndices<Self>. Like Slice, it’s a 
simple wrapper for the base collection and a start and end index — it needs to keep a 
reference to the base collection to be able to advance the indices. This can lead to 
unexpected performance problems if users mutate the collection while iterating over its 
indices: if the collection is implemented using copy-on-write (as all collections in the 
standard library are), the extra reference to the collection can trigger unnecessary 
copies. 

We cover copy-on-write in the chapter on structs and classes. For now, it’s enough to 
know that if your custom collection can provide an alternative Indices type that doesn’t 


need to keep a reference to the base collection, doing so is a worthwhile optimization. 
This is true for all collections whose index math doesn’t rely on the collection itself, like 
arrays or our queue. If your index is an integer type, you can use 
CountabieRange<lndex>: 

extension FIFOQueue:Collection { 

typealias Indices = CountableRange<lnt> 
var indices: CountabieRange<lnt> { 
return startlndex..<endlndex 

} 

} 


Indices 


An index represents a position in the collection. Every collection has two special indices, 
startindex and endindex. The startindex designates the collection’s first element, and 
endindex is the index that comes after the last element in the collection. As a result, 
endl ndex isn’t a valid index for subscripting; you use it to form ranges of indices 
(somelndex..<endlndex) or to compare other indices against, e.g. as the break condition 
in a loop (while someindex < endindex). 

Up to this point, we’ve been using integers as the index into our collections. Array does 
this, and (with a bit of manipulation) our FIFOQueue type does too. Integer indices are 
very intuitive, but they’re not the only option. The only requirement for a collection’s 
Index is that it must be Comparable, which is another way of saying that indices have a 
defined order. 

Take Dictionary, for instance. It would seem that the natural candidates for a 
dictionary’s indices would be its keys; after all, the keys are what we use to address the 
values in the dictionary. But the key can’t be the index because you can’t advance it — 
there’s no way to tell what the next index after a given key would be. Also, subscripting 
with an index is expected to give direct element access, without detours for searching or 
hashing. 

As a result, Dictionaryindex is an opaque value that points to a position in the 
dictionary’s internal storage buffer. It really is just a wrapper for a single Int offset, but 
that’s an implementation detail of no interest to users of the collection. (In fact, the 
reality is somewhat more complex because dictionaries that get passed to or returned 


from Objective-C APIs use an NSDictionary as their backing store for efficient bridging, 
and the index type for those dictionaries is different. But you get the idea.) 

This aiso expiains why subscripting a Dictionary with an index doesn’t return an optionai 
vaiue, whereas subscripting with a key does. The su bscri pt(_ key: Key) we’re so used to is 
an additionai overioad of the subscript operator that’s dehned directiy on Dictionary. It 
returns an optional Value: 

struct Dictionary { 

subscriptfkey: Key) -> Value? 

} 

In contrast, subscripting with an index is part of the Collection protocol and always 
returns a non-optional value, because addressing a collection with an invalid index (like 
an out-of-bounds index on an array) is considered a programmer error and doing so is 
supposed to trap: 

protocol Collection { 

subscript(position: index) -> Element { get} 

} 

Notice the return type Element. A dictionary’s Element type is the tuple type 
(key: Key, value: Value), so for Dictionary, this subscript returns a key-value pair and not 
just a Value. This is also why iterating over a dictionary in a for loop produces key-value 
pairs. 

In the section on array indexing in the built-in collections chapter, we discussed why it 
makes sense even for a “safe” language like Swift not to wrap every failable operation in 
an optional or error construct. “If every API can fail, then you can’t write useful code. 
You need to have some fundamental basis that you can rely on, and trust to operate 
correctly,” otherwise your code gets bogged down in safety checks. 


Index Invalidation 

Indices may become invalid when the collection is mutated. Invalidation could mean 
that the index remains valid but now addresses a different element or that the index is 
no longer a valid index for the collection and using it to access the collection will trap. 
This should be intuitively clear when you consider arrays. When you append an element, 
all existing indices remain valid. When you remove the first element, an existing index 



to the last element becomes Invalid. Meanwhile smaller Indices remain valid, but the 
elements they point to have changed. 

A dictionary index remains stable when new key-value pairs are added until the 
dictionary grows so much that it triggers a reallocation. This is because the element’s 
location in the dictionary’s storage buffer doesn’t change, as elements are inserted until 
the buffer has to be resized, forcing all elements to be rehashed. Removing elements 
from a dictionary invalidates indices . 

An index should be a dumb value that only stores the minimal amount of information 
required to describe an element’s position. In particular, indices shouldn’t keep a 
reference to their collection, if at all possible. Similarly, a collection usually can’t 
distinguish one of its “own” indices from one that came from another collection of the 
same type. Again, this is trivially evident for arrays. Of course, you can use an integer 
index that was derived from one array to index another: 

let numbers = [1,2,3,4] 

let squares = numbers.map {$0 * $0} 

let numbersindex = numbers.index(of:4)!//3 

squares[numberslndex] // 76 

This also works with opaque index types, such as String.Index. In this example, we use 
one string’s startindex to access the first character of another string: 

let hello = "Hello" 
let world = "World" 
let helloldx = hello.startindex 
world[helloldx] //W 

However, the fact that you can do this doesn’t mean it’s generally a good idea. If we had 
used the index to subscript into an empty string, the program would’ve crashed because 
the index was out of bounds. 

There are legitimate use cases for sharing indices between collections, though. The 
biggest one is working with slices. The Collection protocol requires that an index of the 
base collection must address the same element in a slice of that collection, so it’s always 
safe to share indices with slices. 



Advancing Indices 


Swift 3 introduced a major change to the way index traversal is handled for collections. 
The task of advancing an index forward or backward (i.e. deriving a new index from a 
given index) is now a responsibility of the collection, whereas up until Swift 2, indices 
were able to advance themselves. Where you used to write somelndex.successorQ to step 
to the next index, you now write collection.index(after: someindex). 

Why did the Swift team decide to make this change? In short, performance. It turns out 
that deriving an index from another very often requires information about the 
collection’s internals. It doesn’t for arrays, where advancing an index is a simple 
addition operation. But a string index, for example, needs to inspect the actual character 
data because characters have variable sizes in Swift. 

In the old model of self-advancing indices, this meant that the index had to store a 
reference to the collection’s storage. That extra reference was enough to defeat the 
copy-on-write optimizations used by the standard library collections and would result in 
unnecessary copies when a collection was mutated during iteration. 

By allowing indices to remain dumb values, the new model doesn’t have this problem. 
It’s also conceptually easier to understand and can make implementations of custom 
index types simpler. When you do implement your own index type, keep in mind that 
the index shouldn’t keep a reference to the collection if at all possible. In most cases, an 
index can likely be represented with one or two integers that efficiently encode the 
position to the element in the collection’s underlying storage. 

The downside of the new indexing model is a more verbose syntax. 


Custom Collection Indices 

As an example of a collection with non-integer Indices, we’ll build a way to iterate over 
the words in a string. When you want to split a string into its words, the easiest way is to 
use split(separator:maxSplits:omittingEmptySubsequences:). This method is defined on 
Collection, and it turns a collection into an array of Subsequences, split at the provided 
separator: 

var str = "Still I see monsters" 

str.splitfseparator: " ")// ["Still", "I", "see", "monsters"] 



This code returns an array of words. Each word is of type Substring, which is String’s 
associated Subsequence type. Wheneveryou need to spiit a coiiection, the split method 
is aimost aiways the right tooi to use. It does have one disadvantage though: it eageriy 
computes the entire array. If you have a large string and oniy need the first few words, 
this isn’t very efficient. To be more efficient, we buiid a Words coiiection that doesn’t 
compute aii the words up front hut instead aiiows us to iterate iaziiy. 

Let’s start hy hnding the range of the first word in a Substring. We’ii use spaces as word 
boundaries, aithough it’s an interesting exercise to make this conhgurabie. A substring 
might start with an arbitrary number of spaces, which we skip over, start is the substring 
with the ieading spaces removed. We’ii then try to find the next space; if there’s any 
space, we use that as the end of the word boundary. If we can’t hnd any more spaces, we 
use endindex: 

extension Substring { 
var nextWordRange: Range<lndex> { 
let start = dropfwhiie: {$0 == '' ''}) 
let end = start.index(where: {$0 == " ''}) ?? endindex 
return start.startlndex..<end 

} 

} 

Note that Range is haif-open: the upper bound end isn’t included in the word range. 

A logical first choice for the index type of a Words coiiection wouid be Int: the index i 
wouid mean the ith word in the coiiection. However, accessing an eiement through the 
index-hased subscript needs to be 0(1), and in order to hnd the i* word, we’d have to 
process the entire string (which is an 0(n) operation). 

Another choice for the index type wouid be to use String.Index. The collection’s 
startindex would he string.startindex, the index after that would he the index of the 
beginning of the next word, and so on. Unfortunately, the subscript implementation will 
have a similar problem: hnding the end of the word is also 0(n). 

Instead, we make our index a wrapper around Range<Substring.lndex>. A collection’s 
index needs to be Comparable (and because Comparable inherits from Equatable, we 
need to implement = = as well). To compare two indices, we only compare the range’s 
lower bounds. This doesn’t work for comparing Ranges in general, but for our purpose it 
sufhces. By marking the range property and the initializer as fileprivate, we make 
Wordsindex an opaque type; users of our collection don’t know the internal structure, 
and the only way to create an index is through the collection’s interface: 


struct Wordsindex: Comparable { 
fileprivate let range: Range<Substring.lndex> 
fileprivate init(_ value: Range<Substring.lndex>) { 
self.range = value 

} 

staticfunc <(lhs: Words.Index, rhs: Words.Index) -> Bool { 
return Ihs.range.lowerBound < rhs.range.lowerBound 

} 

static func = = (lhs: Words.Index, rhs: Words.Index) -> Bool { 
return Ihs.range == rhs.range 

} 

} 

We’re now ready to build our Words collection. It stores the underlying String as a 
Substring (we’ll see why in the section on slicing) and provides a start index and an end 
index. The Collection protocol requires startindex to have a complexity of 0(1). 
Unfortunately, computing it takes 0{n), where n is the number of spaces at the start of 
the string. Therefore, we compute it in the initializer and store it, instead of defining it 
as a computed property. For the end index, we use an empty range that’s outside the 
bounds of the underlying string: 

struct Words: Collection { 
let string: Substring 
let startindex: Wordsindex 

init(_ s: String) { 
self.init(s[...]) 

} 

private init(_ s: Substring) { 
self.string = s 

self.startlndex = Wordslndex(string.nextWordRange) 

} 

var endindex: Wordsindex { 
let e = string.endindex 
return Wordslndex(e..<e) 

} 


Collection also requires us to provide a subscript that accesses elements. Here we can 
directly use the index’s underlying range. Note that using the range of the word as the 
index makes the implementation 0(1): 

extension Words { 

subscript(index: Wordsindex) -> Substring { 
return string[index.range] 

} 

} 

As the final Collection requirement, we need a way to compute the index following a 
given index. The upper bound of the index’s range is not Included, so unless that’s 
already the string’s endl ndex, we can take the substring from the upper bound onward, 
and then look for the next word range: 

extension Words { 

func index(after i: Wordsindex) -> Wordsindex { 
guard i.range.upperBound < string.endindex 
else { return endindex} 
let remainder = string[i.range.upperBound...] 
return Wordslndex(remainder.nextWordRange) 

} 

} 

Array(Words(" hello world test '').prefix(2))/’"he/io" "world"] 

With some effort, the Words collection could be changed to solve more general problems. 
First of all, we can make the word boundary configurable: instead of using a space, we 
can pass in a function, isWordBoundary: (Character) -> Bool. Second, the code isn’t really 
specific to strings: we could replace String with any kind of collection. For example, we 
could reuse the same algorithm to lazily split Data into processable chunks. 


Slices 


All collections get a default implementation of the slicing operation and have an 
overload for subscript that takes a Range<lndex>. This is the equivalent of list.dropFirstO: 

let words: Words = WordsC'one two three”) 

let onePastStart = words.index(after: words.startindex) 

let firstDropped = words[onePastStart..<words.endindex] 


Array(firstDropped) // f'two", "three"] 


Since operations like words[somewhere..<words.endlndex] (siice from a specific point to 
the end) and words[words.startlndex..<somewhere] (siice from the start to a specific 
point) are common, there are variants in the standard iibrary that do these operations in 
a more readabie way: 

let firstDropped2 = words.suffix(from: onePastStart) 

//or: 

let firstDroppedS = words[onePastStart...] 

By default, the type of firstDropped won’t be Words — it’ll be a Slice<Words>. Slice is a 
lightweight wrapper on top of any collection. The implementation looks something like 
this: 

struct Slice<Base: Collection>: Collection { 
typealias index = Base.index 
typealias indexDistance = Base.indexDistance 
typealias Subsequence = Slice<Base> 

let collection: Base 

var startindex: index 
var endindex; index 

init(base: Base, bounds: Range<index>) { 
collection = base 
startindex = bounds.lowerBound 
endindex = bounds.upperBound 

} 

func index(after i: index) -> index { 
return collection.index(after: i) 

} 

subscript(position: index) -> Base.Element { 
return coilection[position] 

} 

subscript(bounds: Range<Base.index>) -> Slice<Base> { 
return Siice(base: collection, bounds: bounds) 


} 

} 

Slice is a perfectly good default subsequence type, but every time you write a custom 
collection, it’s worth investigating whether or not you can make the collection its own 
Subsequence. For Words, this is easy to do: 

extension Words { 

subscript(range: Range<Wordslndex>) -> Words { 
let start = range.lowerBound.range.lowerBound 
let end = range.upperBound.range.upperBound 
return Words(string[start..<end]) 

} 

} 

The compiler infers the Subsequence type from the return type of the range-based 
subscript. 

Using the same type for a collection and its Subsequence makes life easier for users of 
the collection because they only have to understand a single type instead of two. On the 
flip side, using distinct types for “root” collections and their slices can help prevent 
accidental memory “leaks,” which is why the standard library has ArraySlice and 
Substring. 


Slices Share Indices with the Base Collection 

A formal requirement of the Collection protocol is that indices of a slice can be used 
interchangeably with indices of the original collection: 


A collection and its slices share the same indices. An element of a collection 
is located under the same index in a slice as in the base collection, so long 
as neither the collection nor the slice has been mutated since the slice was 
created. 


An important implication of this model is that, even when using integer indices, a 
collection’s index won’t necessarily start at zero. Here’s an example of the start and end 
indices of an array slice: 



let cities = ["New York", "Rio", "London", "Berlin", 

"Rome", "Beijing", "Tokyo", "Sydney"] 
let slioe = cities[2...4] 
cities.startindex0 
cities.endlndex//8 
slice.startlndex/y2 
slice.endlndex/Y5 

Accidentally accessing slice[0] in this situation will crash your program. This is another 
reason to always prefer constructs like for x in oollection or for index in collection.indices 
over manual index math if possible — with one exception: if you mutate a collection 
while iterating over its indices, any strong reference the indices object holds to the 
original collection will defeat the copy-on-write optimizations and may cause an 
unwanted copy to be made. Depending on the size of the collection, this can have a 
significant negative performance impact. (Not all collections use an indices type that 
strongly references the base collection, but many do because that’s what the standard 
library’s Defaultindices type does.) 

To avoid this issue, you can replace the for loop with a while loop and advance the index 
manually in each iteration, thus avoiding the indices property. Just remember that if 
you do this, always start the loop at collection.startindex and not at 0. 


A Generic Prefixiterator 

Now that we know any collection can be sliced, we could revisit our prefix Iterator code 
from earlier in the chapter and write a version that works with any collection: 

struct Prefixiterator<Base: Collection>: iteratorProtocol, Sequence { 
let base: Base 
var offset: Base.Index 

init(_ base: Base) { 
self, base = base 
self. offset = base.startlndex 

} 

mutatingfunc nextQ -> Base.Subsequence? { 
guard offset != base.endlndex else { return nil} 
base.formlndex(after: &offset) 
return base.prefix(upTo: offset) 


} 

} 

By conforming the iterator directiy to Sequence, we can use it with functions that work 
on sequences without having to define another type: 

let numbers = [1,2,3] 

Array(Prefixlterator(n umbers)) 

./[ArraySlicedl]), ArraySlice([l, 2]), ArrayStice([l, 2, 3])] 


Specialized Collections 

Like aii weii-designed protocois. Collection strives to keep its requirements as smail as 
possibie. In order to aiiow a wide array of types to become coiiections, the protocoi 
shouidn’t require conforming types to provide more than is absoiuteiy necessary to 
impiement the desired functionaiity. 

Two particuiariy interesting iimitations are that a Collection can’t move its indices 
backward, and that it doesn’t provide any functionaiity for mutating the coiiection, such 
as inserting, removing, or repiacing eiements. That isn’t to say that conforming types 
can’t have these capabiiities, of course, oniy that the protocoi makes no assumptions 
about them. 

Some aigorithms have additionai requirements, though, and it would be nice to have 
generic variants of them, even if only some collections can use them. For this purpose, 
the standard library includes four specialized collection protocols, each of which refines 
Collection in a particular way in order to enable new functionality (the quotes are from 
the standard library documentation): 

-> BidirectionalCollection — “A collection that supports backward as well as forward 
traversal.” 

^ RandomAccessCollection — ‘A collection that supports efficient random-access 
index traversal.” 

^ MutableCollection — ‘A collection that supports subscript assignment.” 

^ RangeReplaceableCollection — ‘A collection that supports replacement of an 
arbitrary subrange of elements with the elements of another collection.” 


Let’s discuss them one by one. 


BidirectionalCoUection 

BidirectionalCollection adds a single but critical capability: the ability to move an index 
backward using the index(before:) method. This is sufficient to give your collection a 
default last property, matching first: 

extension BidirectionalCoUection { 

///The last element of the collection. 
public var last: Element? { 
return isEmpty ? nil : self[index(before: endindex)] 

} 

} 

Collection could certainly provide a last property itself, but that wouldn’t be a good idea. 
To get the last element of a forward-only collection, you have to iterate all the way to the 
end, i.e. an 0(n) operation. It’d be misleading to provide a cute little property for the last 
element — a singly linked list with a million elements takes a long time to fetch the last 
element. 

An example of a bidirectional collection in the standard library is String. For 
Unicode-related reasons that we’ll go into in the chapter on strings, a character 
collection can’t provide random access to its characters, but you can move backward 
from the end, character by character. 

BidirectionalCollection also adds more efficient implementations of some operations 
that profit from traversing the collection backward, such as suffix, removeLast, and 
reversed. The latter doesn’t immediately reverse the collection, but instead returns a 
lazy view: 

extension BidirectionalCollection { 

/// Returns a view presenting the elements of the collection in reverse 
/// order. 

/// - Complexity: 0(1) 

public func reversedQ -> ReversedCollection<Self> { 
return ReversedCollection(_base: self) 

} 

} 


Just as with the enumerated wrapper on Sequence, no actual reversing takes place. 
Instead, ReversedCoUection holds the base collection and uses a reversed index into the 
coilection. The coiiection then reverses the logic of ail index traversai methods so that 
moving forward moves backward in the base coiiection, and vice versa. 

Vaiue semantics piay a big part in the vaiidity of this approach. On construction, the 
wrapper “copies” the base coiiection into its own storage so that a subsequent mutation 
of the originai coiiection won’t change the copy heid by ReversedCoUection. This means 
that it has the same observabie behavior as the version of reversed that returns an array. 
We’ii see in the chapter on structs and ciasses that, in the case of copy-on-write types 
such as Array (or immutabie persistent structures like List, or types composed of two 
copy-on-write types iike FIFOQueue), this is stiil an efficient operation. 

Most types in the standard library that conform to Collection also conform to 
BidirectionalCollection. However, types like Dictionary and Set don’t — mostly as the 
idea of forward and backward iteration makes little sense for inherently unordered 
collections. 


RandomAccessCoUection 

A RandomAccessCoUection provides the most efficient element access of all — it can 
jump to any index in constant time. To do this, conforming types must be able to (a) 
move an index any distance, and (b) measure the distance between any two indices, 
both in 0(1) time. RandomAccessCoUection redeclares its associated Indices and 
Subsequence types with stricter constraints — both must be random-access themselves 
— but otherwise adds no new requirements over BidirectionalCollection. Adopters must 
ensure to meet the documented 0(1) complexity requirements, however. You can do 
this either by providing implementations of the index(_:offsetBy:) and distance(from:to:) 
methods, or by using an Index type that conforms to Strideable, such as Int. 

At first, it might seem like RandomAccessCoUection doesn’t add much. Even a simple 
forward-traverse-only collection like our Words can advance an index by an arbitrary 
distance. But there’s a big difference. For Collection and BidirectionalCollection, 
index(_:offsetBy:) operates by incrementing the index successively until it reaches the 
destination. This clearly takes linear time — the longer the distance traveled, the longer 
it’ll take to run. Random-access collections, on the other hand, can just move straight to 
the destination. 


This ability is key in a number of algorithms, a couple of which we’ll look at in the 
chapter on generics. There, we’ll implement a generic binary search, but it’s crucial this 



algorithm be constrained to random-access collections only — otherwise it’d be far less 
efficient than just searching through the collection from start to end. 

A random-access collection can compute the distance between its startindex and 
endindex in constant time, which means the collection can also compute count in 
constant time out of the box. 


MutableCoUection 

A mutable collection supports in-place element mutation. The single new requirement 
it adds to Collection is that the single-element subscript now must also have a setter. We 
can add conformance for our queue type: 

extension FIFOQueue: MutableCoUection { 
public var startindex: Int { return 0} 
public var endindex: Int { return left.count -I- right.count} 

public func indexfafter i: Int) -> Int { 
return i -F 1 

} 

public subscriptfposition: Int) -> Element { 
get{ 

precondition((0..<endlndex).contains(position), "Index out of bounds") 
if position < left.endindex { 
return leftjleft.count - position - 1] 

} else { 

return right[position - left.count] 

} 

} 

set { 

precondition((0..<endlndex).contains(position), "Index out of bounds") 
if position < left.endindex { 
left[left.count - position - 1] = newValue 
} else { 

return right[position - left.count] = newValue 

} 

} 

} 


Notice that the compiler won’t let us add the subscript setter In an extension to an 
existing Collection; it’s neither allowed to provide a setter without a getter, nor can we 
redefine the existing getter, so we have to replace the existing Collection-conforming 
extension. Now the queue is mutable via subscripts: 

var playlist: FIFOQueue = ["Shake It Off", "Blank Space", "Style"] 

playlist.first // Optional("Shake It Off") 

playlist[0] = "You Belong With Me" 

playlist.first/YOpt/ono/C'You Belong With Me") 

Relatively few types in the standard library adopt MutableCollection. Of the three major 
collection types, only Array does. MutableCollection allows changing the values of a 
collection’s elements but not the length of the collection or the order of the elements. 
This last point explains why Dictionary and Set do not conform to MutableCollection, 
although they’re certainly mutable data structures. 

Dictionaries and sets are unordered collections — the order of the elements is undefined 
as far as the code using the collection is concerned. However, internally , even these 
collections have a stable element order that’s defined by their implementation. When 
you mutate a MutableCollection via subscript assignment, the index of the mutated 
element must remain stable, i.e. the position of the index in the indices collection must 
not change. Dictionary and Set can’t satisfy this requirement because their indices point 
to the bucket in their internal storage where the corresponding element is stored, and 
that bucket could change when the element is mutated. 


RangeReplaceableCoUection 

For operations that require adding or removing elements, use the 
RangeReplaceableCoUection protocol. This protocol requires two things: 

-> An empty initializer — this is useful in generic functions, as it allows a function 
to create new empty collections of the same type. 

-> A replaceSubrange(_:with:) method — this takes a range to replace and a 
collection to replace it with. 


RangeReplaceableCoUection is a great example of the power of protocol extensions. You 
implement one uber-flexible method, replaceSubrange, and from that comes a whole 
bunch of derived methods for free: 


^ append(_:) and append(contentsOf:) — replace endindex.xendindex (i.e. replace 
the empty range at the end) with the new element/elements 

^ remove(at:) and removeSubrange(_:) — replace i...i or subrange with an empty 
collection 

-> insert(at:) and in sert(contentsOf:at:) — replace i..<i (i.e. replace the empty range 
at that point in the array) with a new element/elements 

^ removeAll — replace startindex.xendindex with an empty collection 

If a specific collection type can use knowledge about its implementation to perform 
these functions more efficiently, it can provide custom versions that will take priority 
over the default protocol extension ones. 

We chose to have a very simple inefficient implementation for our queue type. As we 
stated when defining the data type, the left stack holds the element in reverse order. In 
order to have a simple implementation, we need to reverse all the elements and combine 
them into the right array so that we can replace the entire range at once: 

extension FIFOQueue: RangeReplaceableCollection { 
mutatingfunc replaceSubrange<C: CoUection>(_ subrange: Range<lnt>, 
with newElements: C) where C.Element == Element 

{ 

right = left.reversedO + right 
left.removeAllQ 

right.replaceSubrange(subrange, with: newElements) 

} 

} 

You might like to try implementing a more efficient version, which looks at whether or 
not the replaced range spans the divide between the left and right stacks. There’s no 
need for us to implement the empty init in this example, since the FIFOQueue struct 
already has one by default. 

Unlike BidirectionalCollection and RandomAccessCollection, where the latter extends 
the former, RangeReplaceableCollection doesn’t inherit from MutableCollection; they 
form distinct hierarchies. An example of a standard library collection that does conform 
to RangeReplaceableCollection but isn’t a MutableCollection is String. The reasons boil 
down to what we said above about indices having to remain stable during a 
single-element subscript mutation, which String can’t guarantee. We’ll talk more about 
this in the chapter on strings. 


The standard library knows twelve distinct kinds of collections that are 
the result of the combination of three traversal methods (forward-only, 
bidirectional, and random-access) with four mutability types (immutable, 
mutable, range-replaceable, and mutable-and-range-replaceable). 

Because each of these needs a specialized default subsequence type, you may 
encounter types like MutableRangeReplaceableBidirectionalSlice. Don’t let 
these monstrosities discourage you from working with them — they behave 
just like a normal Slice, with extra capabilities that match their base collection, 
and you rarely need to care about the specific type. And if and when Swift gets 
conditional protocol conformance, the types will be removed in favor of 
constrained extensions on Slice. 


Composing Capabilities 

The specialized collection protocols can be composed very elegantly into a set of 
constraints that exactly matches the requirements of a particular algorithm. As an 
example, take the sort method in the standard library for sorting a collection in place 
(unlike its non-mutating sibling, sorted, which returns the sorted elements in an array). 
Sorting in place requires the collection to be mutable, if you want the sort to be fast, you 
also need random access. Last but not least, you need to be able to compare the 
collection’s elements to each other. 

Combining these requirements, the sort method is defined in an extension to 
MutableCollection, with RandomAccessCoUection and Element: Comparable as 
additional constraints: 

extension MutableCollection 

where Self: RandomAccessCoUection, Element: Comparable { 

///Sorts the collection in place. 

public mutating func sort() {...} 

} 


Recap 


The Sequence and Collection protocols form the foundation of Swift’s collection types. 
They provide dozens of common operations to conforming types and act as constraints 



for your own generic functions. The specialized collection types, such as 
MutableCollection or RandomAccessCoUection, give you very fine-grained control over 
the functionality and performance requirements of your algorithms. 

The high level of abstraction necessarily makes the model complex, so don’t feel 
discouraged if not everything makes sense immediately. It takes practice to become 
comfortable with the strict type system, especially since, more often than not, 
discerning what the compiler wants to tell you is an art form that forces you to carefully 
read between the lines. The reward is an extremely flexible system that can handle 
everything from a pointer to a memory buffer to a destructively consumed stream of 
network packets. 

This flexibility means that once you’ve Internalized the model, chances are that a lot of 
code you’ll come across in the future will instantly feel familiar because it’s built on the 
same abstractions and supports the same operations. And whenever you create a 
custom type that fits in the Sequence or Collection framework, consider adding the 
conformance. It’ll make life easier both for you and for other developers who work with 
your code. 

The next chapter is all about another fundamental concept in Swift: optionals. 



Optionals 



Sentinel Values 


An extremely common pattern in programming is to have an operation that may or may 
not return a value. 

Perhaps not returning a value is an expected outcome when you’ve reached the end of a 
file you were reading, as in the following C snippet: 

int ch; 

while ((ch = getcharO) != EOF) { 
printfC'Read character %c\n", ch); 

} 

printfC Reached end-of-file\n"); 

EOF is just a #define for -1. As long as there are more characters in the file, getchar 
returns them. But if the end of the file is reached, getchar returns -1. 

Or perhaps returning no value means “not found,” as in this bit of C++: 

auto vec = {1,2, 3}; 

auto iterator = std::find(vec.begin(), vec.endQ, someValue); 
if (iterator != vec.endQ) { 

std::cout « "vec contains " « *iterator << std::endl; 

} 

Here, vec.endQ is the Iterator “one past the end” of the container; it’s a special iterator 
you can check against the container’s end but that you mustn’t ever actually use to 
access a value — similar to a collection’s endindexin Swift. The find function uses it to 
indicate that no such value is present in the container. 

Or maybe the value can’t be returned because something went wrong during the 
function’s processing. Probably the most notorious example is that of the null pointer. 
This innocuous-looking piece of Java code will likely throw a NuUPointerException: 

inti = Integer.getIntegerC'l 23") 

It happens that Integer.getinteger doesn’t parse strings into integers, but rather gets the 
integer value of a system property named “123.” This property probably doesn’t exist, in 
which case getinteger returns null. When the null then gets unboxed into an int, Java 
throws an exception. 


Or take this example in Objective-C: 


[[NSString alloc] initWithContentsOfURL:url 
encoding:NSUTF8StringEncoding error:&e]; 

Here, the NSString might be nil, in which case — and only then — the error pointer 
should be checked. There’s no guarantee the error pointer is valid if the result is non-nil. 

In all of the above examples, the function returns a special “magic” value to indicate that 
it hasn’t returned a real value. Magic values like these are called “ sentinel values .” 

But this approach is problematic. The result returned looks and feels like a real value. 

An int of-1 is still a valid integer, but you don’t ever want to print it out. v.endO is an 
iterator, but the results are undefined if you try to use it. And everyone loves seeing a 
stack dump when your Java program throws a NullPointerException. 

Unlike Java, Objective-C allows sending messages to nil. This is “safe” in so far as the 
runtime guarantees that the return value from a message to nil will always be the 
equivalent of zero, i.e. nil for object return types, 0 for numeric types, and so on. If the 
message returns a struct, it’ll have all its members initialized to zero. With this in mind, 
consider the following snippet: 

NSString *someString = ...; 

if ([someString rangeOfString:@''Swift''].location != NSNotFound) { 

NSLog(@''Someone mentioned Swift!"); 

} 

If someString is nil, whether accidentally or on purpose, the rangeOfString: message will 
return a zeroed NSRange. Hence, its .location will be zero, and the inequality 
comparison against NSNotFound (which is defined as NSintegerMax) will succeed. 
Therefore, the body of the if statement will be executed when it shouldn’t be. 

Null references cause so many problems that Tony Hoare, credited with their creation in 
1965, calls them his “billion-dollar mistake”: 


At that time, I was designing the first comprehensive type system for 
references in an object oriented language (ALGOL W). My goal was to ensure 
that all use of references should be absolutely safe, with checking performed 
automatically by the compiler. But I couldn’t resist the temptation to put in a 





null reference, simply because it was so easy to implement. This has led to 
innumerable errors, vulnerabilities, and system crashes, which have probably 
caused a billion dollars of pain and damage in the last forty years. 


We’ve seen that sentinel values are error-prone — you can forget to check the sentinel 
value and accidentally use it. They also require prior knowledge. Sometimes there’s an 
idiom that’s widely followed in a community, as with the C++ end iterator or the error 
handling conventions in Objective-C. If such rules don’t exist or you’re not aware of 
them, you have to refer to the documentation. Moreover, there’s no way for the function 
to indicate it can’t fail. If a call returns a pointer, that pointer might never be nil. But 
there’s no way to tell except by reading the documentation, and even then, the 
documentation might be wrong. 


Solving the Magic Value Problem with 
Enumerations 


Of course, every good programmer knows magic numbers are bad. Most languages 
support some kind of enumeration type, which is a safer way of representing a set of 
discrete possible values for a type. 

Swift takes enumerations further with the concept of “associated values.’’ These are 
enumeration values that can also have another value associated with them: 

enum Optionai<Wrapped> { 
case none 

case some(Wrapped) 

} 

In some languages, these are called “tagged unions” (or “discriminated unions’’) — a 
union being multiple different possible types all held in the same space in memory, with 
a tag to tell which type is actually held. In Swift enums, this tag is the enum case. 

The only way to retrieve an associated value is through pattern matching in a switch or 
an if case let statement. Unlike with a sentinel value, you can’t accidentally use the 
value embedded in an Optional without explicitly checking and unpacking it. 



So instead of returning an index, the Swift equivalent of find — called index(of:) — 
returns an Optional<lndex> with a protocol extension implementation somewhat similar 
to this: 

extension Collection where Element: Equatable { 
func index(of element: Element) -> Optional<lndex> { 
var idx = startindex 
while idx != endindex { 
if self[idx] == element { 
return .some(idx) 

} 

formlndex(after: &idx) 

} 

// Not found, return .none 
return .none 

} 

} 

Since optionals are fundamental to Swift, there’s lots of syntax support to 
tidy this up: Optional<lndex> can be written Index?; optionals conform to 
ExpressibleByNilLiteral so that you can write nil instead of .none; and 
non-optional values (like idx) are automatically “upgraded” to optionals where 
needed so that you can write return idx instead of return .some(idx). The 
syntactic sugar is effective in disguising the true nature of the Optional type. 

It’s worth remembering that there’s nothing magical about it; it’s just a normal 
enum, and if it didn’t exist, you could define it yourself. 

Now there’s no way a user could mistakenly use the value before checking if it’s valid: 

var array = ["one", "two", "three"] 
let idx = array.index(of: "four") 

// Compile-time error: remove(at:) takes an Int, not an Optianal<lnt> 
array. remove(at: idx) 

Instead, you’re forced to “unwrap” the optional in order to get at the index within, 
assuming you didn’t get none back: 

var array = ["one", "two", "three"] 
switch array.index(of: "four") { 
case .some(let idx): 



array.remove(at: idx) 
case .none: 
break // Do nothing 

} 

This switch statement writes the enumeration syntax for optionais out longhand, 
including unpacking the associated value in the some case. This is great for safety, but 
it’s not very pleasant to read or write. A more succinct alternative is to use the ? pattern 
suffix syntax to match a some optional value, and you can use the nil literal to match 
none: 

switch array.index(of: "four") { 
case let idx?: //Equivalent to .some(let idx) 
array.removefat: idx) 
case nil: 

break //Do nothing 

} 

But this is still clunky. Let’s take a look at all the other ways you can make your optional 
processing short and clear, depending on your use case. 


A Tour of Optional Techniques 

Optionais have a lot of extra support built into the language. Some of the examples 
below might look very simple if you’ve been writing Swift for a while, but it’s important 
to make sure you know all of these concepts well, as we’ll be using them again and again 
throughout the book. 


if let 

Optional binding with if let is just a short step away from the switch statement above: 

var array = ["one", "two", "three", "four"] 
if let idx = array.index(of: "four") { 
array.remove(at: idx) 

} 


An optional binding with if let can have boolean clauses as well. So suppose you didn’t 
want to remove the element if it happened to be the first one in the array: 

if let idx = array.index(of: "four"), idx != array.startindex { 
array.remove(at: idx) 

} 

You can also bind multiple values in the same if statement. What’s more is that later 
entries can rely on the earlier ones being successfully unwrapped. This is very useful 
when you want to make multiple calls to functions that return optionals themselves. For 
example, these URL and Ullmage initializers are all “failable” — that is, they can return 
nil — if your URL is malformed, or if the data isn’t an image. The Data initializer can 
throw an error, and by using try?, we can convert it into an optional as well. All three can 
be chained together, like this: 

let urlString = "https://www.objc.io/logo.png" 
if let url = URL(string: urlString), 
let data = try? Data(contentsOf: url), 
let image = Ullmagefdata: data) 

{ 

let view = UllmageViewfimage: image) 

PlaygroundPage.current.liveView = view 

} 

Any part of a multi-variable let can have a boolean clause as well: 

if let url = URL(string: urlString), url.pathExtension == "png", 
let data = try? Data(contentsOf: url), 
let image = Ullmagefdata: data) 

{ 

let view = UllmageView(image: image) 

} 

If you need to perform a check before performing various if let bindings, you can supply 
a leading boolean condition. Suppose you’re transitioning to a new scene in an iOS app 
and want to check the segue Identifier before casting to a specific kind of view controller: 

if segue.identifier == "showUserDetailsSegue", 
let userDetailVC = segue.destination 
as? UserDetailViewController 

{ 


userDetailVC.screenName = "Hello" 

} 

You can also mix and match optional bindings, boolean clauses, and case let bindings 
within the same if statement. 

This kind of if let binding is a good match for the Scanner type in Foundation, which 
returns a boolean value to indicate whether or not it successfully scanned something, 
after which you can unwrap the result: 

let scanner = Scanner(string: "lisal 23") 
var username: NSString? 
let alphas = CharacterSet.alphanumerics 
if scanner.scanCharacters(from: alphas, into: Stusername), 
let name = username { 
print(name) 

} 


while let 

Very similar to the if let statement is while let — a loop that only terminates when its 
condition returns nil. 

The standard library’s readLine function returns an optional string from the standard 
input. Once the end of input is reached, it returns nil. So to implement a very basic 
equivalent of the Unix cat command, you use while let: 

while let line = readLineO { 
print(line) 

} 

Similar to if let, you can always add a boolean clause to your optional binding. So if you 
want to terminate this loop on either EOF or a blank line, add a clause to detect an empty 
string. Note that once the condition is false, the loop is terminated (you might 
mistakenly think the boolean condition functions like a filter): 

while let line = readLineO, lline.isEmpty { 
print(line) 

} 


As we saw in the chapter on collection protocols, the for x in seq loop requires seq to 
conform to Sequence. This protocol provides a makelterator method that returns an 
iterator, which in turn has a next method, next returns values until the sequence is 
exhausted, and then it returns nil. while let is ideal for this: 

let array =[1,2, 3] 
var iterator = array.makelteratorQ 
while let i = iterator.nextO { 
print(i, terminator: " '') 

}//1 23 

So given that for loops are really just while loops, it’s not surprising that they also 
support boolean clauses, albeit with a where keyword: 

for i in 0..<10 where i % 2 == 0 { 
print(i, terminator: " '') 

}//02468 

Note that the where clause above doesn’t work like the boolean clause in a while loop. In 
a while loop, iteration stops once the value is false, whereas in a for loop, it functions like 
filter. If we rewrite the above for loop using while, it looks like this: 

var iterator2 = (0..<10).makelterator() 
while let i = iterator2.next() { 
ifi%2==0{ 
print(i) 

} 

} 

This feature of for loops avoids a particularly strange bug with variable capture that can 
occur in other languages. Consider the following code, written in Ruby: 

functions = [] 
fori in 1..3 

functions.push(lambda {i}) 

end 

for f in functions 
print ''#{f.call()}" 

end 


Ruby lambdas are like Swift’s closure expressions, and as with Swift, they capture local 
variables. So the above code loops from 1 to 3 — adding a closure to the array that 
captures i — and will print out the value of i when called. Then it loops over that array, 
calling each of the closures. What do you think will be printed out? If you’re on a Mac, 
you can try it out by pasting the above into a hie and running ruby on it from the 
command line. 

If you run it, you’ll see it prints out three 3s in a row. Even though i held a different value 
when each closure was created, they all captured the same i variable. And when you call 
them, i now has the value 3 — its value at the end of the loop. 

Now for a similar Swift snippet: 

var functions: [() -> Int] = [] 
fori in 1...3 { 
functions.append {i} 

} 

for f in functions { 
print("\(f())", terminator: '' ") 

}//7 23 

The output; 1,2, and 3. This makes sense when you realize for...in is really while let. To 
make the correspondence even clearer, imagine there wasn’t a while let, and that you 
had to use an iterator without it: 

var functionsi: [() -> Int] = [] 
var iteratorl = (1 ...3).makelterator() 
var currenti: Int? = iteratorl .nextO 
while currenti != nil { 
let i = currenti! 
functionsi .append {i} 
currenti = iteratorl .nextQ 

} 

This makes it easy to see that i is a fresh local variable in every iteration, so the closure 
captures the correct value even when a new local i is declared on subsequent iterations. 

By contrast, the Ruhy code is more along the lines of the following: 


var functions?: [() -> Int] = [] 


do { 

var iterator2 = (1 ...3).makelterator() 
var i: Int 

var current: Int? = iterator?.nextO 
while current != nil { 
i = current! 

functions?.append {i} 
current = iterator?.nextQ 

} 

} 

Here, i is declared outside the loop — and reused — so every closure captures the same i. 
If you run each of them, they’ll all return 3. The do is there because, despite i being 
declared outside the loop, it’s still scoped in such a way that it isn’t accessible outside 
that loop — It’s sandwiched in a narrow outer shell. 


Most Swift programmers know do blocks as part of the do {try ...} catch (...) 
construct used for error handling. We’ll discuss this usage in the chapter on 
error handling. But do blocks can also be used on their own to introduce a new 
scope. Swift landed on this syntax because C’s keywordless (...) syntax is 
already used for closure expressions in Swift. 


Python behaves like Ruby. C# had the same behavior too — until C# 5, when it was 
decided that this behavior was dangerous enough to justify a breaking change in order to 
make it work like Swift. 


Doubly Nested Optionals 

This is a good time to point out that the type an optional wraps can itself be optional, 
which leads to optionals nested Inside optionals. To see why this isn’t just a strange edge 
case or something the compiler should automatically coalesce, suppose you have an 
array of strings of numbers, which you want to convert into Integers. You might run 
them through a map to convert them: 

let stringNumbers = ["1","?", "three"] 

let maybeints = stringNumbers.map (lnt($0 )} //[Optional(l), Optional(2), nil] 



You now have an array of Optional<lnt> — i.e. Int? — because Int.init(String) is failable, 
since the string might not contain a valid integer. Here, the last entry will be a nil, since 
"three" isn’t an integer. 

When looping over the array with for, you’d rightly expect that each element would be an 
optional integer, because that’s what maybeints contains: 

for maybeint in maybeints { 

// maybeint is an Int? 

//Two numbers and a 'nil' 

} 

Now consider that the implementation of for...in is shorthand for the while loop 
technique above. What’s returned from iterator.nextO would be an 
Optional<Optional<lnt» — or Int?? — because next wraps each element in the sequence 
inside an optional. The while let unwraps it to check it isn’t nil, and while it’s non-nil, 
binds the unwrapped value and runs the body: 

var iterator = maybeints.makelteratorQ 
while let maybeint = iterator.nextO { 
print(maybelnt, terminator: " ") 

} 

// Optional(l) Optional(2) nil 

When the loop gets to the final element — the nil from "three" — what’s returned from 
n ext is a non- n i I value: . so m e(n i 1) . It unwraps this and binds what’s inside (a n i 1) to 
maybeint. Without nested optlonals, this wouldn’t be possible. 

By the way, if you ever want to loop over only the non-nil values with for, you can use 
case pattern matching: 

for case let i? in maybeints { 

//i will be an Int, notan Int? 
print(i, terminator: " ") 

} 

//i 2 

// Or only the nil values: 
for case nil in maybeints { 

// Will run once for each nil 
printC'No value") 


} 

//No value 


This uses a “pattern” of x?, which only matches non-nil values. This is shorthand for 
.some(x), so the loop could be written like this: 

for case let .some(i) in maybeints { 
print(i) 

} 

This case-based pattern matching is a way to apply the same rules that work in switch 
statements to if, for, and while. It’s most useful with optionals, but it also has other 
applications — for example: 

let j = 5 

if case 0..<10 =j { 
print("\(j) within range") 

} //5 within range 

Since case matching is extensible via overloading the ~= operator, this means you can 
extend if case and for case in various interesting ways: 

struct Pattern { 
let s: String 

init(_ s: String) { self.s = s } 

} 

func ~ = (pattern: Pattern, value: String) -> Bool { 
return value.range(of: pattern.s) != nil 

} 

let s = "Taylor Swift" 
if case PatternC'Swift") = s { 
print("\(String(reflecting: s)) contains \"Swift\"") 

} 

// "Taylor Swift" contains "Swift" 

This has incredible potential, but you need to be careful, as it’s very easy to accidentally 
write ~= operators that match a little too much. On that note, inserting the following 
into a common bit of library code would probably be a good April Fools’ joke: 


func ~=<T, U>(_:T,U) -> Bool { return true} 

This code will make every case match (unless a more specific version of ~= is already 
defined). 


if var and while var 

Instead of let, you can use var with if, while, and for. This allows you to mutate the 
variable inside the statement body: 

let number = "1" 
if var i = Int(number) { 
i += 1 
print(i) 

}//2 

But note that i will be a local copy; any changes to i won’t affect the value inside the 
original optional. Optionals are value types, and unwrapping them copies the value 
inside. 


Scoping of Unwrapped Optionals 

Sometimes it feels limiting to only have access to an unwrapped variable within the if 
block it has defined. For example, take the first property on arrays — a property that 
returns an optional of the first element, or nil when the array is empty. This is 
convenient shorthand for the following common bit of code: 

let array = [1,2,3] 
if larray.isEmpty { 
print(array[0]) 

} 

//Outside the block, the compiler can't guarantee that array[0] is valid 

Using the first property, you have to unwrap the optional in order to use it — you can’t 
accidentally forget: 


if let firstElement = array.first { 
print(firstElement) 


} 

//Outside the block,you can't use firstElement 

The unwrapped value is only available inside the if let block. This is impractical if the 
purpose of the if statement is to exit early from a function when some condition isn’t 
met. This early exit can help avoid annoying nesting or repeated checks later on in the 
function. You might write the following: 

func doStuff(withArray a: [Int]) { 
if a.isEmpty { 

return 

} 

//Now use a[0] or a. first! safely 

} 

Here, if let binding wouldn’t work because the bound variable wouldn’t be in scope after 
the if block. But you can nevertheless be sure the array will contain at least one element, 
so force-unwrapping the first element is safe, even if the syntax is still unappealing. 

One option for using an unwrapped optional outside the scope it was bound in is to rely 
on Swift’s deferred initialization capabilities. Consider the following example, which 
reimplements part of the pathExtension property from URL and NSString: 

extension String { 
var fiieExtension: String? { 
let period: String.Index 
if let idx = indexfof:{ 
period = idx 
} else { 
return nil 

} 

let extensionStart = indexfafter: period) 
return Stringfself [extensionStart...]) 

} 

} 


''heUo.txf'.fileExtension /'Opt/or7o/f''txt''J 

The compiler checks your code to conhrm there are only two possible paths: one in 
which the function returns early, and another where period is properly initialized. 
There’s no way period could be nil (it isn’t optional) or uninitialized (Swift won’t let you 


use a variable that hasn’t been initialized). So after the if statement, the code can he 
written without you having to worry about optionals at all. 

However, the two previous examples are pretty ugly. Really, what’s needed is some kind 
of if not let — which is exactly what guard let does: 

func doStuff(withArray a: [Int]) { 
guard let firstElement = a.first else { 
return 

} 

// firstElement is unwrapped here 

} 

And the second example becomes much clearer: 

extension String { 
var fileExtension: String? { 
guard let period = index(of: else { 
return nil 

} 

let extensionStart = index(after: period) 
return String(self[extensionStart...]) 

} 

} 

Anything can go in the else clause here, including multiple statements just like an 
if... else. The only requirement is that the else block must leave the current scope. That 
might mean return, or it might mean calling fatalError (or any other function that 
returns Never). If the guard were in a loop, break or continue would also be allowed. 


A function that has the return type Never signals to the compiler that it’ll never 
return. There are two common types of functions that do this: those that abort 
the program, such as fatalError; and those that run for the entire lifetime of the 
program, like dispatchMain. The compiler uses this information for its control 
flow diagnostics. For example, the else branch of a guard statement must 
either exit the current scope or call one of these never-returning functions. 

Never is what’s called an uninhabited type. It’s a type that has no valid values 
and thus can’t be constructed. Its only purpose is its signaling role for the 



compiler. A function declared to return an uninhabited type can never return 
normally. In Swift, an uninhabited type is implemented as an enu m that has 
no cases: 

publicenum Never {} 


You won’t usually need to define your own never-returning functions unless 
you write a wrapper for fatalError or precondition Failure. One interesting use 
case is while you’re writing new code: say you’re working on a complex switch 
statement, gradually filling in all the cases, and the compiler is bombarding 
you with error messages for empty case labels or missing return values, while 
all you’d like to do is concentrate on the one case you’re working on. In this 
situation, a few carefully placed calls to fatalErrorO can do wonders to silence 
the compiler. Consider writing a function called unimplementedO in order to 
better communicate the temporary nature of these calls: 

func unimplementedO -> Never { 
fatalErrorC'This code path is not implemented yet.'') 

} 


Swift meticulously distinguishes between different kinds of “nothingness.” In 
addition to nil and Never, there’s also Void, which is just another way of writing 
an empty tuple: 

public typealias Void = () 


The most common use of Void or () is in the types of functions that don’t return 
anything, but it has other applications too. For example, consider a reactive 
programming framework that models event streams with an Observable<T> 
type, where T describes the payload type of the emitted event. A text field 
object might provide an Observable<String> that fires an event every time the 
user edits the text. Similarly, a button object sends an event when the user taps 
the button, but it has no additional payload to send — its event stream should 
have the type Observable<()>. 



As David Smith put it. Swift makes a careful distinction between the “absence 
of a thing” (nil), the “presence of nothing” (Void), and a “thing which cannot be’ 
(Never). 


Of course, guard isn’t limited to binding, guard can take any condition you might find in 
a regular if statement, so the empty array example could be rewritten with it: 

func doStuff2(withArray a: [Int]) { 
guard la.isEmpty else { return } 

//Now use a[0] or a. first! safely 

} 

Unlike the optional binding case, this guard isn’t a big win — in fact, it’s slightly more 
verbose than the original return. But it’s still worth considering doing this with any early 
exit situation. For one, sometimes (though not in this case) the inversion of the boolean 
condition can make things clearer. Additionally, guard is a clear signal when reading the 
code; it says: “We only continue if the following condition holds.” Finally, the Swift 
compiler will check that you’re definitely exiting the current scope and raise a 
compilation error if you don’t. For this reason, we’d suggest using guard even when an if 
would do. 


Optional Chaining 

In Objective-C, sending a message to nil is a no-op. In Swift, the same effect can be 
achieved via “optional chaining”: 

delegate?.callback() 

Unlike with Objective-C, though, the Swift compiler will force you to acknowledge that 
the receiver could be nil. The question mark is a clear signal to the reader that the 
method might not be called. 

When the method you call via optional chaining returns a result, that result will also be 
optional. Consider the following code to see why this must be the case: 

let str: String? = "Never say never" 

// We want upper ta be the uppercase string 
let upper: String 
if str != nil{ 



upper = strl.uppercasedO 
} else { 

//No reasonable action to take at this point 
fatalErrorC'No idea what to do now...") 

} 

If str is non-nil, upper will have the desired value. But if str is nil, then upper can’t be set 
to a value. So in the optional chaining case, resu It must be optional, in order to account 
for the possibility that str could’ve been nil: 

let result = str?.uppercased{) // Optionai("NEVER SAY NEVER") 

As the name implies, you can chain calls on optional values: 

let lower = str?.uppercased().lowercased() /'Opt/ono/f'never soy never") 

This might look a bit surprising. Didn’t we just say that the result of optional chaining is 
an optional? So why don’t you need a ?. after uppercasedO? This is because optional 
chaining is a “flattening” operation. If str?.uppercased() returned an optional and you 
called ?.lowercased() on it, then logically you’d get an optional optional. But you just 
want a regular optional, so instead we write the second chained call without the 
question mark to represent the fact that the optionality is already captured. 

On the other hand, if the uppercased method itself returned an optional, then you would 
need to add a second ? to express that you were chaining that optional. For example, 
let’s extend the I nt type with a computed property named half. This property returns the 
result of dividing the integer by two, but only if the number is big enough to be divided. 
When the number is smaller than two, it returns nil: 

extension Int { 
var half: lnt?{ 

guard self < -1 || self > 1 else { return nil} 
return self/ 2 

} 

} 

Because calling half returns an optional result, we need to keep putting in ? when calling 
it repeatedly. After all, at every step, the function might return nil: 


20. half?, half?, half//Opt/ono/p; 


Notice that the compiler is still smart enough to flatten the result type for us. The type of 
the expression above is Int? and not Int???, as you might expect. The latter would give 
you more information — namely, which part of the chain failed — but it would also 
make it a lot more cumbersome to deal with the result, destroying the convenience 
optional chaining adds in the first place. 

Optional chaining also applies to subscripts — for example: 

let dictOfArrays = ["nine": [0,1,2, 3]] 
dictOfArrays["nine"]?[3] // Optional(3) 

Additionally, you can use optional chaining to call optional functions: 

let dictOfFunctions: [String: (Int, Int) -> Int] = [ 

"add":(+), 

"subtract": (-) 

] 

dictOfFunctions["add"]?(1, 1) //0ptional(2) 

This is handy in typical callback situations where a class stores a callback function in 
order to inform its owner when an event occurs. Consider a TextField class: 

class TextField { 
private(set) var text = "" 
var didChange: ((String) -> ())? 

private func textDidChange(newText: String) { 
text = newText 
//Trigger callback if non-nil 
didChange?(text) 

} 

} 

The didChange property stores a callback function, which the text field calls every time 
the user edits the text. Because the text field’s owner doesn’t have to register a callback, 
the property is optional; its initial value is nil. When the time comes to invoke the 
callback (in the textDidChange method above), optional chaining lets us do so in a very 
compact way. 

You can even assign through an optional chain. Suppose you have an optional variable, 
and if it’s non-nil, you wish to update one of its properties: 


struct Person { 
var name: String 
var age: Int 

} 

var optionalLisa: Person? = Person(name: "Lisa Simpson", age: 8) 

//Increment age if non-nil 
if optionalLisa != nil { 
optionalLisa!.age+= 1 

} 

This is rather verbose and ugiy. Note that you can’t use optionai binding in this case. 
Since Person is a struct and thus a vaiue type, the bound variabie is a iocai copy of the 
originai vaiue; mutating the former won’t change the iatter: 

if var lisa = optionalLisa { 

// Mutating lisa doesn't change optionalLisa 
lisa.age += 1 

} 

This would work if Person were a ciass. We’ii taik more about the differences between 
vaiue and reference types in the structs and ciasses chapter. Regardiess, it’s stiii too 
verbose. Instead, you can assign to the chained optional value, and if it isn’t nil, the 
assignment will go through: 

optionalLisa?.age += 1 

A weird (but logical) edge case of this feature is that it works for direct assignment to 
optional values. This is perfectly valid: 

var a: Int? = 5 
a?= 10 

a//0ptional(10) 

var b: Int? = nil 
b?= 10 
b// nil 


Notice the subtle difference between a = 10 and a? = 10. The former assigns a new value 
unconditionally, whereas the latter only performs the assignment if the value of a is 
non-nil before the assignment. 


The nil-Coalescing Operator 


Often you want to unwrap an optional, replacing nil with some default value. This is a 
job for the nil-coalescing operator: 

let stringteger = ”1" 

let number = Int(stringteger) ??0 

So if the string can be converted to an integer, nu mber will be that integer, unwrapped. If 
it isn’t, and Int.init returns nil, the default value of 0 will be substituted. So Ihs ?? rhs is 
analogous to the code Ihs != nil ? Ihsl: rhs. 

“Big deall” Objective-C developers might say. “We’ve had the ?: for ages.” And ?? is very 
similar to Ob|ective-C’s ?:. But there are some differences, so it’s worth stressing an 
important point when thinking about optionals in Swift: optionals are not pointers. 

Yes, you’ll often encounter optionals combined with references when dealing with 
Objective-C libraries. But optionals, as we’ve seen, can also wrap value types. So number 
in the above example is just an Int, not an NSNumber. 

Through the use of optionals, you can guard against much more than just null pointers. 
Consider the case where you want to access the first value of an array — but in case the 
array is empty, you want to provide a default: 

let array = [1,2,3] 
larray.isEmpty ? arrayjO] :0 

Because Swift arrays provide a first property that’s nil if the array is empty, you can use 
the nil-coalescing operator instead: 

array.fi rst ??0//7 

This is cleaner and clearer — the intent (grab the first element in the array) is up front, 
with the default tacked on the end, joined with a ?? that signals “this is a default value.” 
Compare this with the ternary version, which starts first with the check, then the value, 
then the default. And the check is awkwardly negated (the alternative being to put the 
default in the middle and the actual value on the end). And, as is the case with optionals, 
it’s impossible to forget that first is optional and accidentally use it without the check, 
because the compiler will stop you if you try. 


Whenever you find yourself guarding a statement with a check to make sure the 
statement is valid, it’s a good sign optionals would be a better solution. Suppose that 
instead of an empty array, you’re checking a value that’s within the array bounds: 

array.count > 5 ?array[5] '.O/ZO 

Unlike first and last, getting an element out of an array by its index doesn’t return an 
Optional. But it’s easy to extend Array to add this functionality: 

extension Array { 

subscript(guarded idx: Int) -> Element? { 
guard (startlndex..<endlndex).contains(idx) else { 
return nil 

} 

return self[idx] 

} 


This now allows you to write the following: 
arrayiguarded: 5] 77 0//0 

Coalescing can also be chained — so if you have multiple possible optionals and you 
want to choose the first non-nil value, you can write them in sequence: 

let i: Int? = nil 
let j: Int? = nil 
let k: Int? = 42 
i??j??k??0//42 


Sometimes, you might have multiple optional values and you want to choose between 
them in an order, but you don’t have a reasonable default if they’re all nil. You can still 
use ?? for this, but if the final value is also optional, the full result will be optional: 


let m = i ?? j ?? k 
type(of: m) // Optional<lnt> 

This is often useful in conjunction with if let. You can think of this like an “or” 
equivalent of if let: 

if let n = i ??j {//similar to ifi != nil II7 != nil 


print(n) 

} 

If you think of the ?? operator as similar to an “or” statement, you can think of an if let 
with multiple clauses as an “and” statement: 

if let n = i, let m = j {} 

// similar to ifi != nil && j != nil 


Because of this chaining, if you’re ever presented with a doubly nested optional and 
want to use the ?? operator, you must take care to distinguish between a ?? b ?? c 
(chaining) and (a ?? b) ?? c (unwrapping the inner and then outer layers): 

let si: String?? = n\l// nil 

(si ?? "inner") ?? "outer" //inner 

let s2: String?? = .sorr\e(n\[) //Optional(nil) 

(s2 ?? "inner") ?? "outer" //outer 


Using Optionals with String Interpolation 

You may have noticed that the compiler emits a warning when you print an optional 
value or use one in a string interpolation expression: 

let bodyTemperature: Double? = 37.0 
let bloodGlucose: Double? = nil 
print(bodyTemperature) /70pt/ono/f3 7.0) 

// Warning: Expression implicitly coerced from 'Double?' to Any 
printC Blood glucose level:\(bloodGlucose)") /'Bloodglucose level ;nil 
// Warning: String interpolation produces a debug description 
//for an optional value; did you mean to make this explicit? 

This is generally helpful because it’s all too easy for a stray "Optional(...)" or "nil" to 
accidentally creep into a text displayed to the user. You should never use optionals 
directly in user-facing strings and always unwrap them first. Since string interpolation is 
defined for all types (Including Optional), the compiler can’t make this a hard error, 
though — a warning is really the best it can do. 

Sometimes you may want to use an optional in a string interpolation — to log its value 
for debugging, for example — and in that case, the warnings can become annoying. The 


compiler offers several flx-its to silence the warning: add an explicit cast with as Any, 
force-unwrap the value with ! (if you’re certain it can’t be nil), wrap it in 
String(describing:...), or provide a default value with the nil-coalescing operator. 

The latter is often a quick and pretty solution, but it has one drawback: the types on both 
sides of the ?? expression must match, so the default value you provide for a Double? 
must be of type Double. Since the ultimate goal is to turn the expression into a string, it’d 
be convenient if you could provide a string as a default value in the hrst place. 

Swift’s ?? operator doesn’t support this kind of type mismatch — after all, what would 
the type of the expression be if the two sides didn’t have a common base type? But it’s 
easy to add your own operator, especially for the purpose of working with optionals in 
string interpolation. Let’s name it ???: 

infix operator ???: NilCoalescingPrecedence 

public func ???<T>(optional:T?, defaultValue: @autoclosure () -> String) 

-> String 

{ 

switch optional { 

case let value?: return String(describing: value) 
case nil: return defaultValueQ 
} 

} 

This takes any optional T? on the left side and a string on the right. If the optional is 
non-nil, we unwrap it and return its string description. Otherwise, we return the default 
string that was passed in. The ©autoclosure annotation makes sure that we only 
evaluate the second operand when needed. In the chapter on functions, we’ll go into 
this in more detail. 

Now we can write the following and we won’t get any compiler warnings: 

printC'Body temperature: \(bodyTemperature ??? "n/a")") 

// Body temperature: 37.0 

printC'Blood glucose level: \(bloodGlucose ??? ''n/a'')'') 

// Blood glucose level: n/a 


Optional map 


Let’s say we have an array of characters, and we want to turn the hrst element into a 
string: 

let characters: [Character] = ["a", "b", "c"] 

String(characters[0]) //o 

If it’s possible for characters to be empty, we can use an if let to create the string only If 
the array is non-empty: 

var firstCharAsString: String? = nil 
if let char = characters.first { 
firstCharAsString = String(char) 

} 

So now, if the array contains at least one element, firstCharAsString will contain that 
element as a String. But if it doesn’t, firstCharAsString will be nil. 

This pattern — take an optional, and transform it if it isn’t nil — is common enough that 
there’s a method on optlonals to do this. It’s called map, and it takes a closure that 
represents how to transform the contents of the optional. Here’s the above function, 
rewritten using map: 

let firstChar = characters.first.map {String($0 )} // OptionalC'a") 

This map is, of course, very similar to the map on arrays or other sequences. But instead 
of operating on a sequence of values, it operates on just one: the possible one inside the 
optional. You can think of optionals as being a collection of either zero or one values, 
with map either doing nothing to zero values or transforming one. 

Given the similarities, the standard library’s implementation of optional map looks a lot 
like collection map: 

extension Optional { 

func map<U>(transform: (Wrapped) -> U) -> U? { 
if let value = self { 
return transform(value) 

} 

return nil 

} 


} 


An optional map is especiaiiy nice when you aiready want an optional result. Suppose 
you wanted to write another variant of reduce for arrays. Instead of taking an initial 
value, it uses the hrst element in the array (in some languages, this might be called 
reducel, but we’ll call it reduce and rely on overloading): 

Because of the possibility that the array might be empty, the result needs to be optional 
— without an initial value, what else could it be? You might write it like this: 

extension Array { 

func reduce(_ nextPartialResult:(Element, Element) -> Element) -> Element?! 

// first will be nil if the array is empty 
guard let fst = first else { return nil} 
return dropFirst0.reduce(fst, nextPartialResult) 

} 


You can use it like this: 

[1,2, 3,4].reduce(+) .^Opt/ona/flO) 

Since optional map returns nil if the optional is nil, reduce could be rewritten using a 
single return statement (and no guard): 

extension Array { 

func reduce_alt(_ nextPartialResult: (Element, Element) -> Element) 

-> Element? 

{ 

return first.map { 

dropFirst().reduce($0, nextPartialResult) 

} 

} 


} 


Optional flatMap 


As we saw in the built-in collections chapter, it’s common to want to map over a 
collection with a function that returns a collection, but collect the results as a single 
array rather than an array of arrays. 

Similarly, if you want to perform a map on an optional value, but your transformation 
function also has an optional result, you’ll end up with a doubly nested optional. An 
example of this is when you want to fetch the hrst element of an array of strings as a 
number, using first on the array and then map to convert it to a number: 

let stringNumbers = ["1", "2", "3'', "foo"] 

let X = stringN urnbers.first.map {lnt($0) } // 0ptional(0ptional(1)) 

The problem is that since map returns an optional (first might have been nil) and 
Int(someString) returns an optional (the string might not be an integer), the type of x will 
beint??. 

flatMap will instead flatten the result into a single optional. As a result, y will be of type 
Int?: 

let y = stringNumbers.first.flatMap {lnt($0)} // Optionai(T) 

Instead, you could’ve written this with if let, because values that are bound later can be 
computed from earlier ones: 

if let a = stringNumbers.first, let b = Int(a) { 
print(b) 

}//7 

This shows that flatMap and if let are very similar. Earlier in this chapter, we saw an 
example that uses a multiple-if-let statement. We can rewrite it using map and flatMap 
instead: 

let urlString = ''https://www.objc.io/logo.png" 
let view = URUstring: urlString) 

.flatMap { try? Data(contentsOf: $0)} 

.flatMap { Ullmage(data: $0)} 

.map { UllmageView(image: $0)} 


if let view = view { 


PlaygroundPage.current.liveView = view 


Optional chaining is also very similar to flatMap: i?.advance(by: 1) is essentially 
equivalent to i.flatMap {$0.advance(by: 1)}. 

Since we’ve shown that a multiple-if-let statement is equivalent to flatMap, we could 
implement one in terms of the other: 

extension Optional { 

func flatMap<U>(transform: (Wrapped) -> U?) -> U? { 
if let value = self, let transformed = transform(value) { 
return transformed 

} 

return nil 

} 


Filtering Out nils with flatMap 

If you have a sequence and it contains optlonals, you might not care about the nil values. 
In fact, you might just want to ignore them. 

Suppose you wanted to process only the numbers in an array of strings. This is easily 
done in a for loop using optional pattern matching: 

let numbers = ["1", "2", "3", "foo"] 
var sum = 0 

for case let i? in numbers.map({ lnt($0)}) { 
sum += i 

} 

sum // 6 

You might also want to use ?? to replace the nils with zeros: 
numbers.map {lnt($0) }.reduce(0) {$0 + ($1 77 0 )} //6 


But really, you just want a version of map that filters out nil and unwraps the non-nil 
values. Enter the standard library’s overload of flatMap on sequences, which does 
exactly that: 

numbers.flatMap {lnt($0) }.reduce(0, +}//6 

We’ve already seen two flattening maps: flattening a sequence mapped to arrays, and 
flattening an optional mapped to an optional. This is a hybrid of the two: flattening a 
sequence mapped to an optional. 

This makes sense if we return to our analogy of an optional being a collection of zero or 
one thing(s). If that collection were an array, flatMap would be exactly what we want. 

To implement our own version of this operation, let’s first define a flatten that Hlters out 
nil values and returns an array of non-optlonals: 

func flattentS: Sequence, T> 

(source: S) -> [T] where S. Element == T? { 
let filtered = source.lazy.filter {$0 != nil} 
return filtered.map {$0!} 

} 

Ewww, a free function? Why no protocol extension? Unfortunately, there’s no way to 
constrain an extension on Sequence to only apply to sequences of optionals. You’d need 
a two-placeholder clause (one for S, and one for T, as given here), and protocol 
extensions currently don’t support this. 

Nonetheless, it does make flatMap simple to write: 
extension Sequence { 

func flatMap<U>(transform: (Element) -> U?) -> [U] { 
return flatten(source: self.lazy.map(transform)) 

} 

} 

In both these functions, we used lazy to defer actual creation of the array until the last 
moment. This is possibly a micro-optimization, but it might be worthwhile for larger 
arrays. Using lazy saves the allocation of multiple buffers that would otherwise be 
needed to write the intermediary results into. 


Equating Optionals 


Often, you don’t care whether a value is nil or not — just whether it contains (if non-nil) a 
certain value: 

let regex = ''''Hello$'' 

if regex.first == { 

// match only start of string 

} 

In this case, it doesn’t matter if the value is nil or not — if the string is empty, the Hrst 
character can’t be a caret, so you don’t want to run the block. But you still want the 
protection and simplicity of first. The alternative, 
if Iregex.isEmpty && regex[regex.startlndex] == is horrible. 

The code above relies on two things to work. First, there’s a version of = = that takes two 
optionals, with an implementation something like this: 

func = = <T: Equatable>(lhs:T?, rhs:T?) -> Bool { 
switch (Ihs, rhs) { 
case (nil, nil): return true 
case let (x?, y?): return x = = y 
case (_?, nil), (nil, _?): return false 
} 

} 

This overload only works on optionals of equatable types. Given this, there are four 
possibilities: they’re both nil, or they both have a value, or either one or the other is nil. 
The switch exhaustively tests ail four possibilities (hence no need for a default clause). It 
dehnes two nils to be equal to each other, nil to never be equal to non-nil, and two non-nil 
values to be equal if their unwrapped values are equal. 

But this is only half the story. Notice that we did not have to write the following: 

if regex.first == OptionalC''") {//or: == .someC"'") 

// Match only start of string 

} 

This is because whenever you have a non-optional value. Swift will always be willing to 
upgrade it to an optional value in order to make the types match. 


This implicit conversion is incredibly useful for writing clear, compact code. Suppose 
there was no such conversion, but to make things nice for the caller, you wanted a 
version of = = that worked between both optional and non-optional types. You’d have to 
write three separate versions: 

//Both optional 

func == <T: Equatable>(lhs:T?, rhs:T?) -> Bool 
//Ihs non-optional 

func == <T: Equatable>(lhs:T, rhs:T?) -> Bool 
//rhs non-optional 

func == <T: Equatable>(lhs:T?, rhs:T) -> Bool 

But instead, only the hrst version is necessary, and the compiler will convert to optionals 
where necessary. 

In fact, we’ve been relying on this throughout the book. For example, when we 
implemented optional map, we transformed the inner value and returned it. But the 
return value of map is optional. The compiler automatically converted the value for us — 
we didn’t have to write return Optional(transform(value)). 

Swift code constantly relies on this implicit conversion. For example, dictionary 
subscript lookup by key returns an optional (the key might not be present). But it also 
takes an optional on assignment — subscripts have to both take and receive the same 
type. Without implicit conversion, you’d have to write 
myDictC'someKey"] = Optional(someValue). 

Incidentally, if you’re wondering what happens to dictionaries with key-based subscript 
assignment when you assign a nil value, the answer is that the key is removed. This can 
be useful, but it also means you need to be a little careful when dealing with a dictionary 
with an optional value type. Consider this dictionary: 

var dictWithNils: [String: Int?] = [ 

"one": 1, 

"two": 2, 

"none": nil 

] 

The dictionary has three keys, and one of them has a value of nil. Suppose we wanted to 
set the value of the "two" key to nil as well. This will not do that: 


dictWithNils["two''] = nil 


d ictWith N i Is // ["nonenil, "oneOptional( 7 )] 


Instead, it’ll remove the "two" key. 

To change the value for the key, you’d have to write one of the following (they all work, 
so choose whichever you feel is clearer): 

dictWithNils["two"] = Optional(nil) 
dictWithNils["two''] = .some(nil) 
dictWithNils["two'']? = nil 

dictWithNils /^r'none";n//, "one": Optional(l), "two"; nil] 

Note that the third version above is slightly different than the other two. It works 
because the "two" key is already In the dictionary, so it uses optional chaining to set its 
value if successfully fetched. Now try this with a key that isn’t present: 

dictWithNils["three"]? = nil 
dictWithNils.index(forKey: "three ")// nil 

You can see that nothing would be updated/inserted. 


Equatable and == 

Even though optionals have an = = operator, this doesn’t mean they can conform to the 
Equatable protocol. This subtle but Important distinction will hit you in the face if you 
try and do the following: 

// Two arrays of optional integers 
let a: [Int?] = [1,2, nil] 
let b: [Int?] = [1,2, nil] 

//Error: binary operator '= = ' cannot be applied to two [Int?] operands 
a == b 

The problem is that the = = operator for arrays requires the elements of the array to be 
equatable: 

func = = <Element: Equatable>(lhs: [Element], rhs: [Element]) -> Bool 


Optionals don’t conform to Equatable — that would require they Implement == for any 
kind of type they contain, and they only can if that type is itself equatable. In the future. 
Swift will support conditional protocol conformance, and only then will we be able to 
write something like this: 

extension Optional: Equatable where Wrapped: Equatable { 

//No need to implement anything: == is already implemented so long 
// as this condition is met. 

} 

In the meantime, you could implement a version of = = for arrays of optionals, like so: 

func = = <T: Equatable>(lhs: [T?], rhs: [T?]) -> Bool { 
return Ihs.elennentsEqual(rhs) {$0 == $1 } 

} 


Comparing Optionals 

Similar to ==, there used to be implementations of <, >, <=, and >= for optionals. For 
Swift 3.0, these comparison operators were removed for optionals because they can 
easily yield unexpected results. 

For example, nil < .some(_) would return true. In combination with higher-order 
functions or optional chaining, this can be very surprising. Consider the following 
example: 

let temps = ["-459.67", "98.6", "0", "warm"] 
let belowFreezing = temps.filter { Double($0) < 0} 

Because DoubleC'warm") will return nil and nil is less than 0, it’ll be included in the 
belowFreezing temperatures. This is unexpected indeed. 

If you need inequality relations between optionals, you now have to unwrap the values 
first and thereby explicitly state how nil values should be handled. We’ll show an 
example of this in the chapter on functions, where we define a generic function that 
“lifts’’ a regular comparison function into the domain of optionals. 



When to Force-Unwrap 

Given all these techniques for cleanly unwrapping optionals, when should you use !, the 
force-unwrap operator? There are many opinions on this scattered throughout the 
Internet, such as “never,” “whenever it makes the code clearer,” and “when you can’t 
avoid it.” We propose the following rule, which encompasses most of them: 


I Use ! when you’re so certain that a value won’t be nil that you want your 
program to crash if it ever is. 


As an example, take the implementation of flatten: 

func flattentS: Sequence, T> 

(source: S) -> [T] where S.Element == T? { 
let filtered = source.lazy.filter {$0 != nil} 
return filtered.map {$0!} 

} 

Here, there’s no possible way that $0! inside map will ever hit anil, since the nil elements 
were all Altered out in the preceding step. This function could certainly be written to 
eliminate the force-unwrap operator by looping over the array and adding non-nil values 
into an array. But the filter/map version is cleaner and probably clearer, so the ! is 
justlAed. 

However, these cases are pretty rare. If you have full mastery of all the unwrapping 
techniques described in this chapter, chances are there’s a better way. Whenever you do 
And yourself reaching for !, it’s worth taking a step back and wondering if there really is 
no other option. 

As another example, consider the following code that fetches all the keys in a dictionary 
with values matching a certain condition: 

let ages = [ 

"Tim": 53, "Angela": 54, "Craig": 44, 

"deny": 47, "Chris": 37, "Michael": 34, 

] 

ages, keys 

.filter {name in ages[name]! < 50} 

.sortedQ 


//["Chris", "Craig", "Jony", "Michaei"] 


Again, the ! is perfectly safe here — since all the keys came from the dictionary, there’s 
no possible way in which a key could be missing from the dictionary. 

But you could also rewrite the statement to eliminate the need for a force-unwrap 
altogether. Using the fact that dictionaries present themselves as sequences of key-value 
pairs, you could just hlter this sequence and then run it through a map to remove the 
value: 

ages.filter {(_, age) in age < 50} 

.map {(name, _) in name} 

.sortedO 

//["Chris", "Craig", "Jony", "Michaei"] 

This version even has a possible performance benefit because it avoids unnecessary key 
lookups. 

Nonetheless, sometimes life hands you an optional, and you know/of certain that it isn’t 
nil. So certain are you of this that you’d rather your program crash than continue, 
because it’d mean a very nasty bug in your logic. Better to trap than to continue under 
those circumstances, so ! acts as a combined unwrap-or-error operator in one handy 
character. This approach is often a better move than just using the nil chaining or 
coalescing operators to sweep theoretically impossible situations under the carpet. 


The Swift compiler is a little too trigger-happy with its hx-it suggestions in this 
area for our taste. It often suggests adding a force-unwrap when it encounters 
an optional in a place where it expects a non-optional value, presumably 
because it’s the only “hx” It can insert without requesting further input from 
you (like a default value). Things will almost certainly go bad If you apply these 
flx-its blindly. 


Improving Force-Unwrap Error Messages 

That said, even when you’re force-unwrapping an optional value, you have options other 
than using the ! operator. When your program does error, you don’t get much by way of 
description as to why in the output log. 



Chances are, you’ll leave a comment as to why you’re justified in force-unwrapping. So 
why not have that comment serve as the error message too? Here’s an operator,!!; it 
combines unwrapping with supplying a more descriptive error message to be logged 
when the application exits: 

infix operator !! 

func !! <T>(wrapped:T?, failureText: @autoclosure () -> String) ->T{ 
if let X = wrapped { return x } 
fatalError(failureTextO) 

} 

Now you can write a more descriptive error message, including the value you expected 
to be able to unwrap: 


let s = "foo" 

let i = Int(s) !! "Expecting integer, got \"\(s)\"'' 


Asserting in Debug Builds 

Still, choosing to crash even on release builds is quite a bold move. Often, you might 
prefer to assert during debug and test builds, but in production, you’d substitute a valid 
default value — perhaps zero or an empty array. 

Enter the interrobang operator,!?. We define this operator to assert on failed unwraps 
and also to substitute a default value when the assertion doesn’t trigger in release mode: 

infix operator !? 

func !?<T: ExpressibleBylntegerLiteral> 

(wrapped:!?, failureText: @autoclosure () -> String) ->T 

{ 

assert(wrapped != nil, failureTextQ) 
return wrapped ??0 

} 

Now, the following will assert while debugging but print 0 in release: 
lets = "20" 

let i = Int(s) !? "Expecting integer, got \"\(s)\"" 


Overloading for other literal convertible protocols enables a broad coverage of types that 
can be defaulted: 

func !?<T: ExpressibleByArrayLiteral> 

(wrapped:!?, failurelext: @autoclosure () -> String) ->T 

{ 

assert(wrapped != nil, failurelextQ) 
return wrapped ?? [] 

} 

func !?<!: ExpressibleByStringLiteral> 

(wrapped:!?, failure!ext: @autoclosure () -> String) ->! 

{ 

assert(wrapped != nil, failure!ext) 
return wrapped ?? 

} 

And for when you want to provide a different explicit default, or for non-standard types, 
we can dehne a version that takes a pair — the default and the error text: 

func !?<!>(wrapped:!?, 

nilDefault: @autoclosure () -> (value:!, text:String)) ->! 

{ 

assert(wrapped != nil, nilDefaultQ.text) 
return wrapped ?? nilDefaultQ.value 

} 

//Asserts in debug, returns 5 in release 
Int(s) !?(5, "Expected integer") 

Since optionally chained method calls on methods that return Void return Void?, you can 
also write a non-generic version to detect when an optional chain hits anil, resulting in a 
no-op: 

func !?(wrapped: ()?, failure!ext: @autoclosure () -> String) { 
assert(wrapped != nil, failure!ext) 

} 

var output: String? = nil 

output?.write("something") !? "Wasn't expecting chained nil here" 


There are three ways to halt execution. The first option, fatalError, takes a message and 
stops execution unconditionally. The second option, assert, checks a condition and a 
message and stops execution if the condition evaluates to false. In release builds, the 
assert gets removed — the condition isn’t checked (and execution is never halted). The 
third option is precondition, which has the same interface as assert, but doesn’t get 
removed from release builds, so if the condition evaluates to false, execution is stopped. 


Living Dangerously: Implicitly Unwrapped 
Optionals 

Make no mistake: implicitly unwrapped optionals — types marked with an exclamation 
point, such as UlView! — are still optionals, albeit ones that are automatically 
force-unwrapped whenever you use them. Now that we know force-unwraps will crash 
your application if they’re ever nil, why on earth would you use them? Well, two reasons 
really. 

Reason 1: Temporarily, because you’re calling Objective-C code that hasn’t been audited 
for nullability. 

The sole reason implicitly unwrapped optionals even exist is to make interoperability 
with Objective-C and C easier. Of course, on the first day you start writing Swift against 
an existing Objective-C code base, any Objective-C method that returns a reference will 
translate into an implicitly unwrapped optional. Since, for most of Objective-C’s lifetime, 
there was no way to indicate that a reference was nullable, there was little option other 
than to assume any call returning a reference might return a nil reference. But few 
Objective-C APIs actually return null references, so it’d be incredibly annoying to 
automatically expose them as optionals. Since everyone was used to dealing with the 
“maybe null” world of Objective-C objects, implicitly unwrapped optionals were a 
reasonable compromise. 

So you see them in unaudited bridged Objective-C code. But you should never see a pure 
native Swift API returning an implicit optional (or passing one into a callback). 

Reason 2: Because a value is nil very briefly, for a well-defined period of time, and is then 
never nil again. 


For example, if you have a two-phase initialization, then by the time your class is ready 
to use, the implicitly wrapped optionals will all have a value. This is the reason 



Xcode/Interface Builder uses them in the view controiler lifecycle: in Cocoa and Cocoa 
Touch, view controllers create their view lazily, so there exists a time window — after a 
view controller has been initialized but before it has loaded its view — when the view 
objects its outlets reference have not yet been created. 


Implicit Optional Behavior 

While implicitly unwrapped optlonals usually behave like non-optional values, you can 
still use most of the unwrap techniques to safely handle them like optlonals — chaining, 
nil-coalescing, if let, map, or just comparing them to nil all work the same: 

var s: String! = "Hello" 
s‘?.\sEmpty // Optional(faise) 
if let s = s { print(s)} 
s = nil 

s ?? "Goodbye" //Goodbye 

As much as implicit optlonals try to hide their optional-ness from you, there are a few 
times when they behave slightly differently than plain values. For example, you can’t 
pass an implicit optional into a function that takes the wrapped type as an inout: 

func incrementL x: inout Int) { 

X -l-= 1 

} 


var i = 1 // Regular Int 

]ncrement(&\) //Increments i to 2 
var j: Int! = 1 // Implicitly unwrapped Int 
increment(&j) 

// Error: Cannot pass immutable value of type 'Int' as inout argument 

The reason is that inout requires an lvalue, which optlonals (implicitly unwrapped or 
not) aren’t. We’ll have more to say on lvalues in the chapter on functions. 


Recap 


Optlonals are touted as one of Swift’s biggest features for writing safer code, and we 
certainly agree. If you think about it though, the real breakthrough isn’t optlonals — it’s 


non-optionals. Almost every mainstream language has the concept of “null” or “nil”; 
what most of them don’t have is the ability to declare a value as “never nil.” Or, 
alternatively, some types (like non-class types In Objective-C or Java) are “always 
non-nil,” forcing developers to come up with magic values to represent the absence of a 
value. 

APIs whose inputs and outputs are carefully designed with optionals in mind are more 
expressive and easier to use; there’s less need to refer to the documentation because the 
types carry more information. 

All the unwrapping techniques we demonstrated in this chapter are Swift’s attempt to 
make bridging the two worlds of optional and non-optional values as painless as 
possible. Which method you should use is often a matter of personal preference. 



Structs and 
Classes 




In Swift, we can choose from multiple options to store structured data: structs, enums, 
classes, and capturing variables with closures. Most of the public types in Swift’s 
standard library are defined as structs, with enums and classes making up a much 
smaller percentage. Part of this may be the nature of the types in the standard library, 
but it does give an indication as to the importance of structs in Swift. Likewise, many of 
the classes in Foundation now have struct counterparts specifically built for Swift. That 
said, we’ll focus on the differences between structs and classes in this chapter. 
Meanwhile, enums behave in a way that’s similar to structs. 

Here are some of the major things that help distinguish between structs and classes: 

-> Structs (and enums) are value types, whereas classes are reference types. When 
designing with structs, we can ask the compiler to enforce immutability. With 
classes, we have to enforce it ourselves. 

-> How memory is managed differs. Structs can be held and accessed directly, 
whereas class instances are always accessed indirectly through their references. 
Structs aren’t referenced but instead copied. Structs have a single owner, whereas 
class Instances can have many owners. 

-> With classes, we can use inheritance to share code. With structs (and enums), 
inheritance isn’t possible. Instead, to share code using structs and enums, we 
need to use different techniques, such as composition, generics, and protocol 
extensions. 

In this chapter, we’ll explore these differences in more detail. We’ll start by looking at 
the differences between entities and values. Next, we’ll continue by discussing issues 
with mutability. Then we’ll take a look at structs and mutability. After that, we’ll 
demonstrate how to wrap a reference type in a struct in order to use it as an efficient 
value type. Finally, we’ll compare the differences in how memory is managed — 
particularly how memory is managed in combination with closures, and how to avoid 
reference cycles. 


Value Types 

We’re often dealing with objects that need an explicit lifecycle: they’re Initialized, 
changed, and destroyed. For example, a file handle has a clear lifecycle: it’s opened, 
actions are performed on it, and then we need to close it. If we open two file handles that 
otherwise have the same properties, we still want to keep them separate. In order to 
compare two file handles, we check whether they point to the same address in memory. 



Because we compare addresses, file handles are best Implemented as reference types, 
using objects. This is what the FileHandle class in Foundation does. 

Other types don’t need to have a lifecycle. For example, a URL is created and then never 
changed. More importantly, it doesn’t need to perform any action when it’s destroyed 
(in contrast to the file handle, which needs to be closed). When we compare two URL 
variables, we don’t care whether they point to the same address in memory, rather we 
check whether they point to the same URL. Because we compare URLs by their 
properties, we say that they’re values. In Objective-C, they were implemented as 
immutable objects using the NSURL class. However, the Swift counterpart, URL, is a 
struct. 

In all software, there are many objects that have a lifecycle — file handles, notification 
centers, networking interfaces, database connections, and view controllers are some 
examples. For all these types, we want to perform specific actions on initialization and 
when they’re destroyed. When comparing these types, we don’t compare their 
properties, but instead compare their memory addresses. All of these types are 
implemented as classes, and all of them are reference types. 

There are also many values at play in most software. URLs, binary data, dates, errors, 
strings, notifications, and numbers are only defined by their properties. When we 
compare them, we’re not interested in their memory addresses. All of these types can be 
implemented using structs. 

Values never change; they’re immutable. This is (mostly) a good thing, because code 
that works with immutable data is much easier to understand. The immutability 
automatically makes such code thread-safe too: anything that can’t change can be safely 
shared across threads. 

In Swift, structs are designed to build values. Structs can’t be compared by reference; we 
can only compare their properties. And although we can declare mutable struct 
variables (using var), it’s important to understand that the mutability only refers to the 
variable and not the underlying value. Mutating a property of a struct variable is 
conceptually the same as assigning a whole new struct (with a different value for the 
property) to the variable. 

Structs have a single owner. For instance, if we pass a struct variable to a function, that 
function receives a copy of the struct, and it can only change its own copy. This is called 
value semantics (sometimes also called copy semantics). Contrast this with the way 
objects work: they get passed by reference and can have many owners. This is called 
reference semantics. 



Because structs only have a single owner. It’s not possible to create a reference cycle. But 
with classes and functions, we need to always be careful to not create reference cycles. 
We’ll look at reference cycles in the section on memory. 

The fact that values are copied all the time may sound inefficient; however, the compiler 
can optimize away many superfluous copy operations. It can do this because structs are 
very basic things. A struct copy is a shallow bitwise copy (except if it contains any 
classes — then it needs to increase the reference count for those). When structs are 
declared with let, the compiler knows for certain that none of those bits can be mutated 
later on. And there are no hooks for the developer to know when the struct is being 
copied, unlike with similar value types in C++. This simplicity gives the compiler many 
more possibilities for eliminating copy operations or optimizing a constant structure to 
be passed by reference rather than by value. 

Copy optimizations of a value type that might be done by the compiler aren’t the same as 
the copy-on-write behavior of a type with value semantics. Copy-on-write has to be 
implemented by the developer, and it works by detecting that the contained class has 
shared references. 

Unlike the automatic elimination of value type copies, you don’t get copy-on-write for 
free. But the two optimizations — the compiler potentially eliminating unnecessary 
“dumb” shallow copies, and the code inside types like Array that perform “smart” 
copy-on-write — complement each other. We’ll look at how to implement your own 
copy-on-write mechanism shortly. 

If a struct is composed out of other structs, the compiler can enforce immutability. Also, 
when using structs, the compiler can generate really fast code. For example, the 
performance of operations on an array containing just structs is usually much better 
than the performance of operations on an array containing objects. This is because 
structs usually have less Indirection: the values are stored directly inside the array’s 
memory, whereas an array containing objects contains just the references to the objects. 
Finally, in many cases, the compiler can put structs on the stack rather than on the heap. 

When interfacing with Cocoa and Objective-C, we often need to use classes. For example, 
when implementing a delegate for a table view, there’s no choice: we must use a class. 
Many of Apple’s frameworks rely heavily on subclassing. Flowever, depending on the 
problem domain, we can still create a class where the objects are values. For example, in 
the Core Image framework, the Cl I mage objects are immutable: they represent an image 
that never changes. 



It’s not always easy to decide whether your new type should be a struct or a class. Both 
behave very differently, and knowing the differences will help you make a decision. In 
the examples in the rest of this chapter, we’ll look in more detail at the implications of 
value types and provide some guidance for when to use structs. 


Mutability 

In recent years, manipulating mutable state has earned a bad reputation, and often 
deservedly so. It’s named as a major cause of bugs, and most experts recommend you 
work with immutable objects where possible, in order to write safe, maintainable code. 
Luckily, Swift allows us to write safe code while preserving an intuitive mutable coding 
style at the same time. 

To see how this works, let’s start by showing some of the problems with mutation. In 
Foundation, there are two classes for arrays: NSArray, and its subclass, NSMutableArray. 
We can write the following (crashing) program using NSMutableArray: 

let mutableArray: NSMutableArray = [1,2,3] 
for_ in mutableArray { 
m utab leArray. re m ove LastO bj ect() 

} 

You’re not allowed to mutate an NSMutableArray while you’re Iterating through it, 
because the iterator works on the original array, and mutating it corrupts the iterator’s 
internal state. Once you know this, the restriction makes sense, and you won’t make that 
mistake again. However, consider that there could be a different method call in the place 
of mutableArray.removeLastObjectO, and that method might mutate mutableArray. Now 
the violation becomes much harder to see, unless you know exactly what that method 
does. 

Now let’s consider the same example, but using Swift arrays: 

var mutableArray = [1,2, 3] 
for_ in mutableArray! 
mutableArray.removeLastO 

} 

This example doesn’t crash, because the iterator keeps a local, independent copy of the 
array. To see this even more clearly, you could write removeAll instead of removeLast, 


and if you open it up in a piayground, you’ii see that the statement gets executed three 
times because the iterator’s copy of the array stiil contains three eiements. 

Classes are reference types. If you create an instance of a class and assign it to a new 
variable, both variables point to the same object: 

let mutableArray: NSMutableArray = [1,2,3] 
let otherArray = mutableArray 
mutableArray.add(4) 

OtherArray7,2,3,4 j 

Because both variables refer to the same object, they now both refer to the array 
[1,2, 3, 4], since changing the value of one variable also changes the value of the other 
variable. This is a very powerful thing, but it’s also a great source of bugs. Calling a 
method might change something you didn’t expect to change, and your invariant won’t 
hold anymore. 

Inside a class, we can control mutable and immutable properties with var and let. For 
example, we could create our own variant of Foundation’s Scanner, but for binary data. 
The Scanner class allows you to scan values from a string, advancing through the string 
with each successful scanned value. A Scanner does this by storing a string and its 
current position in the string. Similarly, our class, BinaryScanner, contains the position 
(which is mutable, hence declared with var) and the original data (which will never 
change, hence declared with let). This is all we need to store in order to replicate the 
behavior of Scanner: 

class BinaryScanner { 
var position: int 
let data: Data 
init(data: Data) { 
self.position = 0 
self.data = data 

} 

} 

We can also add a method that scans a byte. Note that this method is mutating: it 
changes the position (unless we’ve reached the end of the data): 

extension BinaryScanner { 
func scanByteQ -> UintS? { 
guard position < data.endindex else { 


return nil 


} 

position += 1 
return data[position-1] 

} 


To test it out, we can write a function that scans all the remaining hytes and prints them: 

func scanRemainingBytes(scanner: BinaryScanner) { 
while let byte = scanner.scanByteQ { 
print(byte) 

} 

} 

let scanner = BinaryScanner(data: Data("hi".utf8)) 
scanRemainingBytes(scanner: scanner) 

/* 

704 

705 
*/ 


Everything works as expected. However, it’s easy to construct an example with a race 
condition. If we use Grand Central Dispatch to call scanRemainingBytes from two 
different threads, it’ll eventually run into a race condition. In the code below, the 
condition position < data.endindex can be true on one thread, but then GCD switches to 
another thread and scans the last byte. Now, when control switches back to the first 
thread, the position will be incremented and the subscript will access a value that’s out 
of bounds: 

for_ in 0..<lnt.max { 

let newScanner = BinaryScannerfdata: Data("hi".utf8)) 

DispatchQueue.globalQ.async { 
scanRemainingBytesfscanner: newScanner) 

} 

scanRennainingBytes(scanner: newScanner) 

} 

The race condition doesn’t occur too often (hence the Int.max), and is therefore difficult 
to hnd during testing. If we change BinaryScanner to a struct, this problem doesn’t occur 
at all. In the next section, we’ll look at why. 


Structs 


Value types imply that whenever a variable is assigned to another variable, the value 
itself — and not just a reference to the value — is copied. For example, in almost all 
programming languages, scalar types are value types. This means that whenever a value 
is assigned to a new variable, it’s copied rather than passed by reference: 

var a = 42 
var b = a 
b+= 1 
b//43 
a//42 

After the above code executes, the value of b will be 43, but a will still be 42. This is so 
natural that it seems like stating the obvious. However, in Swift, all structs behave this 
way — not just scalar types. 

Let’s start with a simple struct that describes a Point. This is similar to CGPoint, except 
that it contains Ints, whereas CGPoint contains CGFioats: 

struct Point { 
var x: Int 
vary: Int 

} 

For structs. Swift automatically adds a memberwise initializer. This means we can now 
initialize a new variable: 

let origin = Point(x: 0, y: 0) 

Because structs in Swift have value semantics, we can’t change any of the properties of a 
struct variable that’s defined using let. For example, the following code won’t work: 

origin.X =10 4^ Error 

Even though we defined x within the struct as a var property, we can’t change it, because 
origin is declared using let. This has some major advantages. For example, if you read a 
line like let point = ..., and you know that point is a struct variable with value semantics, 
then you also know that it’ll never, ever, change. This is incredibly helpful when reading 
through code. 


To create a mutable variable, we need to use var: 


var otherPoint = Point(x: 0, y: 0) 
otherPoint.x +=10 
otherPoint//fx; W,y:0) 

Unlike with objects, every struct variable is unique. For example, we can create a new 
variable, thirdPoint, and assign the value of origin to it. Now we can change thirdPoint, 
but origin (which we defined as an immutable variable using let) won’t change: 

var thirdPoint = origin 
thirdPoint.X += 10 
third Point/7(x; 10,y:0) 
origin //(x: 0, y: 0) 

When you assign a struct to a new variable. Swift automatically makes a copy. Even 
though this sounds very expensive, many of the copies can be optimized away by the 
compiler, and Swift tries hard to make the copies very cheap. In fact, many structs in the 
standard library are implemented using a technique called copy-on-write, which we’ll 
look at later. 

Structs can also contain other structs. For example, if we define a Size struct, we can 
create a Rectangle struct, which is composed out of a point and a size: 

struct Size { 
var width: Int 
var height: Int 

} 

struct Rectangle { 
var origin: Point 
var size: Size 

} 

Just like before, we get a memberwise initializer for Rectangle. Here, we first define a 
type property on Poi nt, l.e. a property that exists on the type rather than on instances of 
the type. The type property Point.zero effectively acts like a factory initializer for a 
commonly used specific Point instance. We then use that value to initialize a Rectangle: 

extension Point { 
static let zero = Point(x: 0, y: 0) 


} 


let rect = Rectangle(origin: Point.zero, 
size: Size(width: 320, height: 480)) 

If we want a custom initializer for our struct, we can add it directly inside the struct 
definition. However, if the struct definition contains a custom initializer. Swift doesn’t 
generate a memberwise initializer. By defining our custom initializer in an extension, 
we also get to keep the memberwise initializer: 

extension Rectangle { 

init(x: Int = 0, y: Int = 0, width: Int, height: Int) { 
origin = Point(x: X, y: y) 
size = Size(width: width, height: height) 

} 

} 

Instead of setting origin and size directly, we could’ve also called self.init(origin:size:). 


Mutation Semantics 

If we define a mutable variable screen, we can add a didSet block that gets executed 
whenever screen is changed. This didSet works for every definition of a struct, be it in a 
playground, as a member of a class or other struct, or as a global variable: 

var screen = Rectangle(width: 320, height: 480) { 
didSet { 

printC'Screen changed :\(screen)") 

} 

} 

Maybe somewhat surprisingly, even if we change something deep inside the struct, the 
didSet handler will get triggered: 

screen.origin.x = ^Q//Screen changed: (10, 0, 320,480) 

Understanding why this works is key to understanding value types. Mutating a struct 
variable is semantically the same as assigning a new value to it. And even if only one 
property of a larger struct gets mutated, it’s the equivalent of replacing the entire struct 


with a new value. A mutation deep inside a tree of nested structs trickles all the way up 
the tree to the outermost Instance, triggering any willSet and didSet handlers it 
encounters along the way. 

Although, semantically, the entire struct is replaced with a new one, this is usually no 
less efficient; the compiler can still mutate the value in place. Since the struct has no 
other owner, it doesn’t actually need to make a copy. With copy-on-write structs (which 
we’ll discuss later), this works differently. 

Since the collection types in the standard library are structs, they naturally behave the 
same way. Appending an item to an array will trigger the array’s didSet handler, as will 
mutating one of the array’s elements directly through a subscript: 

var screens: [Rectangle] = [] { 

didSet { 

printC'Screens array changed: \(screens)") 

} 

} 

screens.append(Rectangle(width: 320, height: 480)) 

// Screens array changed: [(0, 0, 320,480)} 

screens[0].origin.x -l-= 100/^Screens array changed: [(100, 0, 320, 480)] 

The didSet trigger wouldn’t fire if Rectangle were a class, because in that case, the 
reference the array stores doesn’t change — only the object it’s referring to does. 


Mutating Methods 

Assume we want to add a translate method to Rectangle, which moves the rectangle by a 
given offset. We’ll need to add the offset to the rectangle’s current origin, so let’s start by 
adding an overload for the + operator that adds two Points together and returns a new 
Point: 

func -l-(lhs: Point, rhs: Point) -> Point { 
return Point(x: Ihs.x -t rhs.x, y: Ihs.y + rhs.y) 

} 

screen.origin + Point(x: 10, y: ^Q) //(x: 10,y: 10) 

We now have everything we need to implement translate, yet our first attempt doesn’t 
work: 


extension Rectangle { 
func translate(by offset: Point) { 

// Error: Cannot assign to property: 'self is immutable 
origin = origin + offset 

} 

} 

The compiler complains that we can’t assign to the origin property because self is 
immutable (writing origin = is shorthand for self.origin =). We can think of self as an 
extra, implicit parameter that gets passed to each method. You never have to pass the 
parameter, but it’s always there inside the method body, and it’s immutable so that value 
semantics can be guaranteed. If we want to mutate self, or any property of self, or even 
nested properties (e.g. self.origin.x), we need to mark the method as mutating: 

extension Rectangle { 
mutating func translate(by offset: Point) { 
origin = origin + offset 

} 

} 

screen.translate(by: Point(x: 10,y: 10)) 
screen//(10, 10,320,480) 

The compiler enforces the mutating keyword. Unless we use it, we’re not allowed to 
mutate any part of self inside the method. By marking the method as mutating, we 
change the behavior of self inside that method. Instead of it being a let, it now works like 
a var: we can freely change any of its mutable properties. (To be precise, it’s not even a 
var, but we’ll get to that in a little bit). 

The mutating keyword also determines which methods can be called on variables 
declared with let. Anything that’s marked as mutating may only be called on instances 
declared with var: 

let otherScreen = screen 

// Error: Cannot use mutating member on immutable value 
otherScreen.translate(by: Point(x: 10, y: 10)) 

Thinking back to the built-in collections chapter, we can now see how the difference 
between let and var applies to collections as well. The append method on arrays is 
dehned as mutating, and therefore, we’re not allowed to call it on an array declared with 
let. 


Property setters are implicitly mutating; that’s why you can’t call a setter on a let 
variable: 

let point = Point.zero 

// Error: Cannot assign to property: 'point' is a 'let' constant 
point.X = 10 


mutating is also how wiUSet and didSet “know” when to hre: any invocation of 
a mutating method or an implicitly mutating setter will trigger the observers. 


In many cases, it makes sense to have both a mutable and an immutable variant of the 
same method. For example, arrays have both a sort() method (which is mutating and 
sorts in place) and a sortedQ method (which returns a new array). We can also add a 
non-mutating variant of our translate(by:_) method. Instead of mutating self, we create a 
copy, mutate that, and return a new Rectangle: 

extension Rectangle { 

func translated(by offset: Point) -> Rectangle { 
var copy = self 
copy.translate(by: offset) 
return copy 

} 

} 

screen.translated(by: Point(x: 20, y: 20))//(30, 30,320,480) 


The names sort and sorted aren’t chosen at random — they conform to the 
Swift API Design Guidelines . Methods that have a side effect should read as an 
imperative verb phrase, such as sort. Non-mutating variants of those methods 
should have an -ed or -ing suffix. We applied the same guidelines to translate 
and translated. 


As we saw earlier, it’s easy to introduce bugs when working with mutable objects. Swift 
structs with mutable properties and mutating methods don’t have this problem. The 
mutation of the struct is a local side effect, and it only applies to the variable being 
modified. Because every struct variable is unique (or in other words: every struct value 
has exactly one owner), it’s almost impossible to introduce bugs this way — that is, 
unless you’re accessing a global or captured struct variable from multiple threads 
(closures capture by reference by default). 




How mutating Works: inout Parameters 


To understand how the mutating keyword works, we need to take a look at the inout 
keyword. Before we do that, let’s define a free function that moves a rectangle by 10 
points on both axes. We can’t simply call translate directly on the rectangle parameter, 
because all function parameters are immutable by default and get passed in as copies. 
Instead, we need to use translated(by:) and return the translated rectangle as a new 
value. Callers that want to use the function to mutate an existing value have to reassign 
the result manually: 

func translatedByTenTen(rectang[e: Rectangle) -> Rectangle { 
return rectangle.translated(by: Point(x: 10,y: 10)) 

} 

screen = translated ByTenTen(rectangle: screen) 
screen//f70, 10,320,480) 

How could we write a function (not a method) that changes a Rectangle in place? We’ve 
seen that the mutating keyword does exactly that for methods: it makes the implicit self 
parameter mutable. 

Free functions can achieve the same effect by marking one or more parameters as inout. 
Just like with a regular parameter, a copy of the value gets passed in to the function. 
However, inside the function body the argument becomes mutable — it’s as if It were 
defined as a var. And once the function returns. Swift copies the (possibly mutated) 
value from the function back to the caller, overwriting the original value. 

Using inout, we can write a translate function that mutates the rectangle that gets passed 
in. Notice that we’re now allowed to use translate(by:) in the function body because 
rectangle is mutable: 

func translateByTwentyTwenty(rectangle: inout Rectangle) { 
rectangle.translate(by: Point(x: 20, y: 20)) 

} 

translateByTwentyTwenty(rectangle: &screen) 
screen // (30, 30, 320,480) 

The translateByTwentyTwenty function takes the screen rectangle, changes it locally, 
and copies the new value back (overriding the previous value of screen). This behavior is 
exactly the same as that of a mutating method. In fact, mutating methods are just like 
regular methods on the struct, except the implicit self parameter is marked as inout. 


Accordingly, we can’t call translateByTwentyTwenty on a rectangle that’s defined using 
let. We can only use it with mutable values: 

let immutableScreen = screen 

// Error: Cannot pass immutable value as inout argument 
translateByTwentyTwenty(rectangle: StimmutableScreen) 

We’ll go into more detail about inout in the functions chapter. For now, it suffices to say 
that inout is in lots of places. For example, it’s now easy to understand how mutating a 
value through a subscript works: 

var array = [Point(x: 0, y: 0), Point(x: 10, y: 10)] 
array[0] += Point(x: 100,y: 100) 
array700,y; 100), (x: 10,y: 10)] 

The expression array[0] is automatically passed in as an inout variable. In the functions 
chapter, we’ll see why we can use some expressions (like array[0]) as inout parameters 
and not others. 

Operators that mutate their left-hand side, such as -t=, also require that parameter to be 
inout. Here’s an implementation of -t= for Point. The compiler wouldn’t allow the 
assignment to Ihs if we omitted the inout: 

func -l-=(lhs: inout Point, rhs: Point) { 
lbs = lbs -t rbs 

} 

var myPoint = Point.zero 
myPoint -l-= Point(x: 10,y: 10) 
my Point / (x: 10, y: 10) 


Value Types Can Help Avoid Concurrency Bugs 

Let’s revisit the BinaryScanner example from the introduction of this chapter. We had 
the following prohlematic code snippet: 

for_ in 0..<lnt.max { 

let newScanner = BinaryScanner(data: Data("bi''.utf8)) 

DispatcbQueue.globalQ.async { 
scanRemainingBytes(scanner; newScanner) 


} 

scanRemainingBytes(scanner: newScanner) 

} 

If we make BinaryScanner a struct instead of a class, each call to scanRemainingBytes 
gets its own independent copy of newScanner. Therefore, the calls can safely keep 
iterating over the array without having to worry that the struct gets mutated from a 
different method or thread. Since the two threads no longer share a single position value, 
this small change fundamentally alters the program’s behavior: it’ll now print each byte 
twice per loop iteration. 

Also keep in mind that structs don’t magically make your code thread-safe. For example, 
if we keep BinaryScanner as a struct but inline the scanRemainingBytes method, we end 
up with the same race condition we had before. The two while loops refer to the same 
newScanner variable and will mutate it from different threads at the same time: 

for_ in 0..<lnt.max { 

let newScanner = BinaryScanner(data: Data("hi".utf8)) 

DispatchQueue.globalQ.async { 
while let byte = newScanner.scanByteQ { 
print(byte) 

} 

} 

while let byte = newScanner.scanByteQ { 
print(byte) 

} 


Copy-On-Write 

In the Swift standard library, collections like Array, Dictionary, and Set are implemented 
using a technique called copy-on-write. Let’s say we have an array of integers: 

varx = [1,2,3] 

If we create a new variable, y, and assign the value of x to it, a copy gets made, and both x 
and y now contain independent structs: 


var y = X 


Internally, each of these Array stmcts contains a reference to some memory buffer. This 
buffer is where the actual elements of the array are stored. At this point, both arrays 
reference the same buffer — the arrays are sharing this part of their storage. However, 
the moment we mutate x, the shared reference gets detected, and the buffer is copied. 
This means we can mutate both variables independently, yet the (expensive) copy of the 
elements only happens when it has to — once we mutate one of the variables: 

x. append(5) 

y. removeLastO 
x//[l,2, 3,5] 

This behavior is called copy-on-write. The way it works is that whenever an array is 
mutated, it first checks if its reference to the storage buffer is unique, i.e. if the array is 
the sole owner of the buffer. If so, the buffer can be mutated in place; no copy has to be 
made. However, if the buffer has more than one owner (as in this example), the array will 
create a copy of the buffer and then mutate the copy, leaving the other owners 
unaffected. 

As the author of a struct, copy-on-write behavior isn’t something you get for free; you 
have to implement it yourself. Implementing copy-on-write for your own types makes 
sense whenever you dehne a struct that contains a mutable reference but should still 
retain value semantics. Maintaining value semantics would normally require an 
expensive copy on every mutation, but copy-on-write avoids copying unless it’s 
absolutely necessary. 


Implementing Copy-On-Write 

As an example of a custom type with copy-on-write behavior, let’s recreate the Data 
struct from Foundation and use the NSMutabieData class as our internal reference type. 
Data has value semantics, and it behaves just like Array: 

var input: [UIntS] = [0x0b,0xad,0xf0,0x0d] 
var other; [UIntS] = [OxOd] 
var d = Data(bytes: input) 
var e = d 

d.append(contentsOf: other) 
d // 5 bytes 
e//4 bytes 


As we can see above, d and e are independent: adding a byte to d doesn’t change the 
vaiue of e. 

Writing the same exampie using NSMutableData, we can see that types with reference 
semantics behave differentiy: 

var f = NSMutableData(bytes: &input, length; input.count) 
var g = f 

f.append(8tother, length: other.count) 
f//<0badf00d 0d> 
g -7 WbadfOOd 0d> 


Both f and g refer to the same object (in other words: they point to the same piece of 
memory), so changing one also changes the other. We can even verify that they refer to 
the same object by using the = = = operator: 


f = = = g // true 


If we naively wrap NSMutableData in a struct, we don’t get value semantics 
automatically. For example, we could try the following: 

struct MyData { 
var_data: NSMutableData 
init(_ data: NS Data) { 

_data = data.mutableCopyO as! NSMutableData 

} 

} 

If we copy a struct variable, a shallow copy is made. This means the reference to the 
NSMutableData object, and not the object itself, will get copied: 

let theData = NSData(base64Encoded: "wAEP/w= = ")! 
let X = MyData(theData) 
let y = X 

x._data = = = y._data//true 


We can add an append function, which delegates to the underlying _data property, and 
again, we can see that we’ve created a struct without value semantics: 

extension MyData { 
func append(_ byte: UIntS) { 


var mutableByte = byte 
_data.append(&mutableByte, length: 1) 

} 


x.append(0x55) 

y//<c0010fff55> 


Because we’re only modifying the object _data is referring to, we don’t even have to mark 
append as mutating. After all, the reference stays constant, and the struct too. Therefore, 
we were able to declare x and y using let, even though they were mutable. 


Copy-On-Write (The Expensive Way) 

To arrive at a working implementation, let’s take the term copy-on-write literally: every 
time we need to mutate _data, we’ll make a copy of it first and then mutate the copy. 
This approach won’t be very efficient because we’ll make a ton of unnecessary copies, 
but it will achieve our goal of giving MyData value semantics — other instances 
referencing the original _data object won’t be affected by the mutation. 

Instead of mutating _data directly, we access it exclusively through a computed 
property, _dataForWriting. It’s the getter of this property that copies the NSMutableData 
instance and returns the copy: 

struct MyData { 

fileprivate var _data: NSMutableData 
fileprivate var _dataForWriting: NSMutableData { 
mutating get { 

_data = _data.mutableCopy() as! NSMutableData 
return _data 

} 

} 

initO { 

_data = NSMutableDataO 

} 

init{_ data: NS Data) { 

_data = data.mutableCopyO as! NSMutableData 

} 

} 


Because _dataForWriting mutates the struct (it assigns a new value to the _data 
property), the getter has to be marked as mutating. This means we can oniy use it on 
variables declared with var. 

We can use _dataForWriting in our append method, which now also needs to he marked 
as mutating: 

extension MyData { 
mutatingfunc appendL byte: UIntS) { 
var mutableByte = byte 

_dataForWriting.append(&mutableByte, length: 1) 

} 

} 

Our struct now has value semantics. If we assign the value of x to the variable y, both 
variables are still pointing to the same underlying NSMutableData object. However, the 
moment we use append on either one of the variables, a copy gets made: 

let theData = NSData(base64Encoded: "wAEP/w= = ")! 
varx = MyData(theData) 
let y = X 

x._data = = = y._data // true 

x.append(0x55) 

y//<c0010fff> 

x._data = = = y._data4'fa/se 


This strategy works, but it’s wasteful if we mutate the same variable multiple times. 
Consider the following example: 

var buffer = MyData(NSData()) 
for byte in 0..<5 as CountableRange<Ulnt8> { 
buffer.append(byte) 

} 

Each time we call append, the underlying _data object gets copied. Because buffer 
doesn’t share its storage with other MyData instances, it’d have been a lot more efficient 
(and just as safe) to mutate it in place. 


Copy-On-Write (The Efficient Way) 

To provide efficient copy-on-write behavior, we need to know whether an object (e.g. the 
NSMutableData instance) is uniquely referenced. If it’s a unique reference, we can 
modify the object in place. Otherwise, we create a copy of the object before modifying it. 
In Swift, we can use the isKnownUniquelyReferenced function to And out if a reference 
has oniy one owner. If you pass in an instance of a Swift ciass to this function, and if no 
one eise has a strong reference to the object, the function returns true. If there are other 
strong references, it returns false. Unfortunately, it aiso returns false for Objective-C 
classes. Therefore, it doesn’t make sense to use the function with NSMutableData 
directly. However, we can write a simple Swift class that wraps any Objective-C object (or 
any other value) into a Swift object: 

final class Box<A> { 
var unbox: A 

init(_ value: A) { self.unbox = value} 

} 

varx = Box(NSMutableData()) 
isKnownUniquelyReferenced(&x) //true 

If we have multiple references to the same object, the function will return false: 
var y = X 

isKnownUniquelyReferenced(&x) //false 

This also works when the references are inside a struct and not just global variables. 
Using this knowledge, we can now write a variant of My Data, which checks whether 
_data is uniquely referenced before mutating it. Let’s also add a print statement to 
quickly see during debugging how often we make a copy: 

struct MyData { 

private var_data: Box<NSMutableData> 
var_dataForWriting: NSMutableData { 

mutating get { 

if lisKnownUniquelyReferenced(&_data) { 

_data = Box(_data.unbox.mutableCopyO asl NSMutableData) 
printC'Making a copy") 

} 

return _data.unbox 


} 


} 

initO { 

_data = Box(NSMutableData()) 

} 

init(_ data: NS Data) { 

_data = Box(data.mutableCopy() as! NSMutableData) 

} 

} 

In the _dataForWriting getter, we now need to unbox the _data property to access the 
NSMutableData instance. The append method can remain unchanged because the logic 
for when to make a copy is fully contained inside _dataForWriting: 

extension MyData { 
mutatingfunc appendL byte: UIntS) { 
var mutableByte = byte 

_dataForWriting.append(&mutableByte, length: 1) 

} 

} 

To test out our code, let’s write the loop again: 

var bytes = MyDataQ 
var copy = bytes 

for byte in 0..<5 as CountableRange<Ulnt8> { 
printC'Appending Ox\(String(byte, radix: 16))”) 
bytes.append(byte) 

} 

/* 

Appending 0x0 
Making a copy 
Appending 0x7 
Appending 0x2 
Appending 0x3 
Appending 0x4 
*/ 

bytes//<00010203 04> 
copy//<> 


If we run the code above, we can see that our debug statement only gets printed once: 
when we call append for the first time. In subsequent iterations, the uniqueness is 
detected and no copy gets made. 

This technique allows you to create custom structs that retain value semantics while still 
being just as efficient as you would be working with objects or pointers. As a user of the 
struct, you don’t need to worry about copying these structs manually — the 
Implementation will take care of it for you. Because copy-on-write is combined with 
optimizations done by the compiler, many unnecessary copy operations can be 
removed. 

When you define your own structs and classes. It’s important to pay attention to the 
expected copying and mutability behavior. Structs are expected to have value semantics. 
When using a class inside a struct, we need to make sure that it’s truly immutable. If this 
isn’t possible, we either need to take extra steps (like above), or just use a class, in which 
case consumers of our data don’t expect it to behave like a value. 

Most data structures in the Swift standard library are value types using copy-on-write. 
For example, arrays, dictionaries, sets, and strings are all structs. This makes it simpler 
to understand code that uses those types. When we pass an array to a function, we know 
the function can’t modify the original array: it only works on a copy of the array. Also, 
the way arrays are implemented, we know that no unnecessary copies will be made. 
Contrast this with the Foundation data types, where it’s best practice to always manually 
copy types like NSArray and NSString. When working with Foundation data types, it’s 
easy to forget to manually copy the object and instead accidentally write unsafe code. 

Even when you could create a struct, there might still be very good reasons to use a class. 
For example, you might want an immutable type that only has a single instance, or 
maybe you’re wrapping a reference type and don’t want to implement copy-on-wrlte. Or, 
you might need to interface with Objective-C, in which case, structs might not work 
either. By defining a restrictive interface for your class, it’s still very possible to make it 
immutable. 

It might also be interesting to wrap existing types in enums, which are also value types, 
just like structs. In the chapter on wrapping CommonMark, we’ll provide an 
enum-based interface to a reference type. 



Copy-On-Write Gotchas 


Unfortunately, it’s all too easy to introduce accidental copies. To see this behavior, we’ll 
create a very simple struct that contains a reference to an empty Swift class. The struct 
has a single mutating method, change, which checks whether or not the reference should 
be copied. Rather than copying, it just returns a string indicating whether or not a copy 
would have occurred: 

final class Empty {} 

struct COWStruct { 
var ref = Empty!) 

mutatingfunc change!) -> String { 
if isKnownUniquelyReferenced!&ref) { 
return "No copy" 

} else { 
return "Copy" 

} 

// Perform actual change 

} 


For example, if we create a variable and immediately mutate it, the variable isn’t shared. 
Therefore, the reference is unique and no copy is necessary: 

var s = COWStruct!) 
s.change!) // No copy 

As we’d expect, when we create a second variable, the reference is shared, and a copy is 
necessary the moment we call change: 

var original = COWStruct!) 
var copy = original 
original.change!) Copy 

When we put one of our structs in an array, we can mutate the array element directly, 
and no copy is necessary. This is because accessing an element via array subscripting 
has direct access to the memory location: 


var array = [COWStruct!)] 


array[0].change() /^A/o copy 


If we go through an intermediate variabie, though, a copy is made: 

var otherArray = [COWStructQ] 
var X = array[0] 
x.changeQ // Copy 

Somewhat surprisingiy, ali other types — inciuding dictionaries, sets, and your own 
types — behave very differently. For example, the dictionary subscript looks up the 
value in the dictionary and then returns the value. Because we’re dealing with value 
semantics, a copy is returned. Therefore, calling changeQ on that value will make a copy, 
as the COWStruct is no longer uniquely referenced: 

var diet = ["key'':COWStruct()] 
dict["key'']?.change() // OptionalC'Copy") 

If you want to avoid making copies when you put a copy-on-write struct inside a 
dictionary, you can wrap the value inside a class box, effectively giving the value 
reference semantics. 

When you’re working with your own structs, you need to keep this in mind. For example, 
if we create a container that simply stores a value, we can either modify the storage 
property directly, or we can access it indirectly, such as through a subscript. When we 
directly access it, we get the copy-on-write optimization, but when we access it 
indirectly through a subscript, a copy is made: 

struct ContainerStruct<A> { 
var storage: A 
subscript(s: String) -> A { 
get { return storage} 
set {storage = newValue} 

} 

} 

vard = ContainerStruct(storage: COWStructQ) 
d.storage.changeQ //A/o copy 
d[''test'']. changeQ // Copy 


The implementation of the Array subscript uses a special technique to make 
copy-on-write work, but unfortunately, no other types currently use this. The Swift team 
mentioned that they hope to generalize it to dictionaries . 

The way Array implements the subscript is by using addressors. An addresser allows for 
direct access to memory. Instead of returning the element, an array subscript returns an 
addresser for the element. This way, the element memory can be modihed in place, and 
unnecessary copies can be eliminated. You can use addressors in your own code, but as 
they’re not officially documented, they’re bound to change. For more information, see 
the Accessors.rst document in the Swift repository. 


Closures and Mutability 

In this section, we’ll look at how closures store data. 

For example, consider a function that generates a unique integer every time it gets 
called (until it reaches Int.max). It works by moving the state outside of the function. In 
other words, it closes over the variable i: 

var i = 0 

func uniqueIntegerO -> Int { 
i += 1 

return i 

} 

Every time we call this function, the shared variable i will change, and a different integer 
will be returned. Functions are reference types as well — if we assign uniqueinteger to 
another variable, the compiler won’t copy the function (or i). Instead, it’ll create a 
reference to the same function: 

let otherFunction: () -> Int = uniqueinteger 

Calling otherFunction will have exactly the same effect as calling uniqueinteger. This is 
true for all closures and functions: if we pass them around, they always get passed by 
reference, and they always share the same state. 

Recall the function-based fibsiterator example from the collection protocols chapter, 
where we saw this behavior before. When we used the iterator, the iterator itself (being a 




function) was mutating its state. In order to create a fresh iterator for each iteration, we 
had to wrap it in an AnySequence. 

If we want to have multiple different unique integer providers, we can use the same 
technique: instead of returning the integer, we return a closure that captures the 
mutable variable. The returned closure is a reference type, and passing it around will 
share the state. However, calling uniqueIntegerProvider repeatedly returns a fresh 
function that starts at zero every time: 

func uniquelntegerProviderQ -> () -> Int { 
var i = 0 
return { 
i += 1 

return i 

} 

} 

Instead of returning a closure, we can also wrap the behavior in an Anylterator. That way, 
we can even use our integer provider in a for loop: 

func uniquelntegerProviderQ -> Anylterator<lnt> { 
var i = 0 

return Anylterator { 
i += 1 

return i 

} 

} 

Swift structs are commonly stored on the stack rather than on the heap. For mutable 
structs this is an optimization, though; a struct variable is created on the heap by default, 
and the optimizer will then move it to the stack in almost all cases. The reason the 
compiler works in this way is that variables that are captured by an escaping closure 
need to outlive their stack frame. When the compiler recognizes that a struct variable is 
closed over by a function, it doesn’t apply the optimization and the struct remains on 
the heap. That way, the I variable in our example persists even when the scope of 
uniqueIntegerProvider exits. 


Memory 

Value types are very common in Swift, and memory management for them is very easy. 
Because they have a single owner, the memory needed for them is created and freed 
automatically. When using value types, you can’t create cyclic references. For example, 
consider the following snippet: 

struct Person { 
let name: String 
var parents: [Person] 

} 

var John = Person(name: "John", parents: []) 

John.parents = [John] 

John,/ John, parents: [John, parents: []] 

Because of the way value types work, the moment we put John in an array, a copy is 
created. It’d he more precise to say: “we put the value of John in an array.” If Person were 
a class, we’d now have a cycle. With the struct version, John now has a single parent, 
which is the initial value of John with an empty parents array. 

For classes. Swift uses automatic reference counting (ARC) to manage memory. In most 
cases, this means things will work as expected. Every time you create a new reference to 
an object (for example, when you assign a value to a class variable), the reference count 
gets increased by one. Once you let go of that reference (for example, the variable goes 
out of scope), the reference count decreases by one. When the reference count goes to 
zero, the object is deallocated. A variable that behaves in this manner is also called a 
strong reference (compared to weak or unowned references, which we’ll discuss in a bit). 

For example, consider the following code: 

class View { 
var window: Window 
init(window: Window) { 
self.window = window 

} 

} 

class Window { 
var rootView: View? 


} 


We can now allocate and Initialize a window and assign the Instance to a variable. After 
the first line, the reference count is one. The moment we set the variable to nil, the 
reference count of our Window instance is zero, and the instance gets deallocated: 

var myWindow: Window? = WindowQ .^refcount; 7 
myWindow = n\i //refcountiO, deallocating 

When comparing Swift to a garbage-collected language, at first glance it looks like things 
are very similar when it comes to memory management. Most times, you don’t even 
think about it. However, consider the following example: 

var window; Window? = Window!) /'w/ndow; 7 

var view: View? = Viewfwindow: window!) // window: 2, view: 7 

window?.rootView = view // window:2, view:2 

view = nil //window: 2, view: 7 

window = nil// window: 7, view: 7 

First, the window gets created, and the reference count for the window will be one. The 
view gets created and holds a strong reference to the window, so the window’s reference 
count will be two, and the view’s reference count will be one. Then, assigning the view as 
the window’s rootView will Increase the view’s reference count by one. Now, both the 
view and the window have a reference count of two. After setting both variables to nil, 
they still have a reference count of one. Even though they’re no longer accessible from a 
variable, they strongly reference each other. This is called a reference cycle, and when 
dealing with graph-like data structures, we need to be very aware of this. Because of the 
reference cycle, these two objects will never be deallocated during the lifetime of the 
program. 


Weak References 

To break the reference cycle, we need to make sure that one of the references is either 
weak or unowned. When you mark a variable as weak, assigning a value to it doesn’t 
change the reference count. Weak references in Swift are always zeroing: the variable 
will be automatically set to nil once the referred object gets deallocated — this is why 
weak references must always be optionals. 


Rewriting the exampie above, we could make the window’s rootView property weak, 
which means it won’t strongly reference the view and automatically becomes nil once 
the view is deallocated. To see what’s going on, we can add some print statements to the 
classes’ deinitializers, deinit gets called just before a class deallocates: 

class View { 
var window: Window 
init(window: Window) { 
self.window = window 

} 

deinit { 

printC'Deinit View") 

} 

} 

class Window { 
weak var rootView: View? 
deinit { 

printC'Deinit Window") 

} 

} 

In the code below, we again create a window and a view. As before, the view strongly 
references the window; but because the window’s rootView is declared as weak, the 
window doesn’t strongly reference the view anymore. This way, we have no reference 
cycle, and both objects get deallocated when we set the variables to nil: 

var window: Window? = Window!) 
var view: View? = View(window: window!) 
window?.rootView = view 
window = nil 
view = nil 
/* 

Deinit View 
Deinit Window 
*/ 


Weak references are very useful when working with delegates, as is common in Cocoa. 
The delegating object (e.g. a table view) needs a reference to its delegate, but it shouldn’t 
own the delegate because that would likely create a reference cycle. Therefore, delegate 


references are usually weak, and another object (e.g. a view controller) is responsible for 
making sure the delegate stays around for as long as needed. 


Unowned References 

Weak references must always be optional types because they can become nil, but 
sometimes we may not want this. For example, maybe we know that our views will 
always have a window (so the property shouldn’t be optional), but we don’t want a view 
to strongly reference the window. In other words, assigning to the property should leave 
the reference count unchanged. For these situations, there’s the unowned keyword: 

class View{ 

unowned var window: Window 
init(window; Window) { 
self.window = window 

} 

deinit { 

printC'Deinit View") 

} 

} 

class Window { 
var rootView: View? 

deinit { 

printC'Deinit Window") 

} 

} 

In the code below, we can see that both objects get deallocated, as in the previous 
example with a weak reference: 

var window: Window? = WindowQ 
var view: View? = View(window: window!) 
window?.rootView = view 
view = nil 
window = nil 
/* 

Deinit Window 
Deinit View 
*/ 


So there’s still no reference cycle, but now we’re responsible for ensuring that the 
window outlives the view. If the window is deallocated and the unowned variable is 
accessed, there’ll be a runtime crash. 


The Swift runtime keeps a second reference count in the object to keep track of unowned 
references. When all strong references are gone, the object will release all of its resources 
(for example, any references to other objects). However, the memory of the object itself 
will still be there until all unowned references are gone too. The memory is marked as 
Invalid (sometimes also called zombie memory), and any time we try to access an 
unowned reference, a runtime error will occur. 

Note that this Isn’t the same as undefined behavior. There’s a third option, 
unowned(unsafe), which doesn’t have this runtime check. If we access an invalid 
reference that’s marked as unowned(unsafe), we get undefined behavior. 


Choosing Between Unowned and Weak References 

Should you prefer unowned or weak references in your own APIs? Ultimately, this 
question boils down to the lifetimes of the objects involved. If the objects have 
independent iifetimes — that is, if you can’t make any assumptions about which object 
will outlive the other — a weak reference is the only possible choice. 

On the other hand, if you can guarantee that the non-strongly referenced object has the 
same iifetime as its counterpart or will always outlive it, an unowned reference is often 
more convenient. This is because it doesn’t have to be optional and the variable can be 
declared with let, whereas weak references must always be optional vars. Same-lifetime 
situations are very common, especially when the two objects have a parent-child 
relationship. When the parent controls the child’s lifetime with a strong reference and 
you can guarantee that no other objects know about the child, the child’s back reference 
to its parent can always be unowned. 

Unowned references also have less overhead than weak references, so accessing a 
property or calling a method on an unowned reference will be slightly faster; this should 
only be a factor in very performance-critical code paths, however. 

The downside of preferring unowned references is of course that your program may 
crash if you make a mistake in your lifetime assumptions. Personally, we often find 
ourselves preferring weak even when unowned could be used because the former forces 
us to explicitly check if the reference is still valid at every point of use. We might want to 



refactor some code at a later point, and our earlier assumptions about object lifetimes 
might not be valid anymore. 


But there’s definitely an argument to be made to always use the modifier that captures 
t he lifetime characteristics you expect your code to have in order to make them explicit. 
If you or someone else later changes the code in a way that invalidates those 
assumptions, a hard crash is arguably the sensible way to alert you to the problem — 
assuming you find the bug during testing. 


Closures and Memory 

Classes aren’t the only kind of reference type in Swift. Functions are reference types too, 
and this includes closures. As we saw in the section on closures and mutability, a closure 
can capture variables. If these variables are themselves reference types, the closure will 
maintain a strong reference to them. For example, if you have a variable handle that’s a 
FileHandle object and you access it within a callback, the callback will increment the 
reference count for that handle: 

let handle = FileHandlefforWritingAtPath: "out.html”) 

let request = URLRequest(url: URL(string: ''https://www.objc.io'')!) 

URLSession.shared.dataTaskfwith: request) {(data, _) in 
guard let theData = data else { return } 

// Closure keeps strong reference to handle 
hand le?.write(the Data) 

}.resume() 

Once the callback is done, the URL session releases the closure, and the variables it 
closes over (in the example above, just handle) will have their reference counts 
decremented. This strong reference to the closed-over variables is necessary, otherwise 
the variable could already be deallocated when you access it within the callback. 

Only closures that can escape need to keep strong references to their variables. In the 
chapter on functions, we’ll look into more detail at escaping vs. non-escaping functions. 


Reference Cycles with Closures 

One of the issues with closures capturing their variables is the (accidental) introduction 
of reference cycles. The usual pattern is like this: object A references object B, but object 




B stores a callback that references object A. Let’s consider our example from before, 
where a view references its window, and the window has a weak reference back to its 
root view. Additionally, the window now has an on Rotate callback, which is optional and 
has an initial value of nil: 

class View { 
var window: Window 
init(window: Window) { 
self.window = window 

} 

deinit { 

printC'Deinit View") 

} 

} 

class Window { 
weak var rootView: View? 
var onRotate: (() -> ())? 

deinit { 

printC'Deinit Window") 

} 

} 

If we create a view and set up the window like before, all is well, and we don’t have a 
reference cycle yet: 

var window: Window? = WindowQ 
var view: View? = View(window: window!) 
window?.rootView = view 

The view has a strong reference to the window, but the window has a weak reference to 
the view, so there’s no cycle. However, if we configure the on Rotate callback and use the 
view in there, we’ve introduced a reference cycle: 

window?.onRotate = { 

printC'We now also need to update the view:\(view)") 

} 

The view references the window, the window references the callback, and the callback 
references the view: a cycle. 


In a diagram, it looks like this: 


The closure retains 
the View... 



the closure 


Figure 5.1; A retain cycle between the view, window, and closure 


We need to find a way to break this cycle. There are three places where we could break 
the cycle (each corresponding to an arrow in the diagram): 

-> We could make the reference to the Window weak. Unfortunately, this would 
make the Window disappear, because there are no other references keeping it 
alive. 

-> We might want to change the Window to make the onRotate closure weak, but 
Swift doesn’t allow marking closures as weak. 

-> We could make sure the closure doesn’t reference the view by using a capture list. 
This is the only correct option in the above example. 


In the case of the (constructed) example above, it’s not too hard to figure out that we 
have a reference cycle. However, it’s not always this easy. Sometimes the number of 
objects involved might be much larger, and the reference cycle might be harder to spot. 
And to make matters even worse, your code might be correct the first time you write it, 
but a refactoring might introduce a reference cycle without you noticing. 








Capture Lists 


To break the cycle above, we want to make sure the closure won’t reference the view. We 
can do this by using a capture list and marking the captured variabie (view) as either 
weak or unowned: 

window?.onRotate = {[weak view] in 
printC'We now also need to update the view:\(view)'') 

} 

Capture lists can also be used to initialize new variabies. For exampie, if we wanted to 
have a weak variabie that refers to the window, we could initialize it in the capture list, or 
we could even define completely unrelated variables, like so: 

window?.onRotate = {[weak view, weak myWindow=window, x=5*5] in 
printC'We now also need to update the view: \(view)") 
printC'Because the window \(myWindow) changed") 

} 

This is almost the same as defining the variable just above the closure, except that with 
capture lists, the scope of the variable is just the scope of the closure; it’s not available 
outside of the closure. 


Recap 

We’ve looked at the differences between structs and classes in Swift. For entities 
(needing identity), classes are a better choice. For value types, structs are a better choice. 
When building structs that contain objects, we often need to take extra steps to ensure 
that they retain value semantics — for example, by implementing copy-on-write. We’ve 
looked at how to prevent reference cycles when dealing with classes. Often, a problem 
can be solved with either structs or classes, and what you choose depends on your needs. 
However, even problems that are classically solved using references can often benefit 
from values. 


Encoding and 
Decoding 
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Serializing a program’s internal data structures into some kind of data Interchange 
format and vice versa is one of the most common programming tasks. Swift calls these 
operations encoding and decoding. One of the headline features of Swift 4 is a 
standardized design for encoding and decoding data that all custom types can opt into. 


Overview 


The Codable system (named after its base “protocol,” which is really a type alias) is 
designed around three central goals: 

-> Universality — It should work with structs, enums, and classes. 

-> Type safety — Interchange formats such as JSON are often weakly typed, 
whereas your code should work with strongly typed data structures. 

-> Reducing boilerplate — Developers should have to write as little repetitive 
“adapter code” as possible to let custom types participate in the system. The 
compiler should generate this code for you automatically. 

Types declare their ability to be (de-)serialized by conforming to the Encodable and/or 
Decodable protocols. Each of these protocols has just one requirement — Encodable 
defines an encode(to:) method in which a value encodes itself, and Decodable specifies 
an initializer for creating an instance from serialized data: 

///A type that can encode itself to an external representation. 
public protocol Encodable { 

///Encodes this value into the given encoder. 
public func encode(to encoder: Encoder) throws 

} 

///A type that can decode itself from an external representation. 
public protocol Decodable { 

/// Creates a new instance by decoding from the given decoder. 
public init(from decoder: Decoder) throws 

} 

Because most types that adopt one will also adopt the other, the standard library 
provides the Codable typealias as a shorthand for both: 


public typealias Codable = Decodable & Encodable 


All basic standard library types — Including Bool, the number types, and String — are 
codable out of the hox, as are optionals, arrays, dictionaries, and sets containing codable 
elements. Lastly, many common data types used hy Apple’s frameworks have already 
adopted Codable, including Data, Date, URL, CGPoint, and CGRect. 

Once you have a value of a codable type, you can create an encoder and tell it to serialize 
the value into the target format, such as JSON. In the reverse direction, a decoder takes 
serialized data and turns it back into an instance of the originating type. On the surface, 
the corresponding Encoder and Decoder protocols aren’t much more complex than 
Encodable and Decodable. The central task of an encoder or decoder is to manage a 
hierarchy of containers that store the serialized data. While you rarely have to interact 
with the Encoder and Decoder protocols directly unless you’re writing your own coders, 
understanding this structure and the three kinds of containers is necessary when you 
want to customize how your own types encode themselves. We’ll see many examples of 
this helow. 


A Minimal Example 

Let’s begin with a minimal example of how you’d use the Codable system to encode an 
instance of a custom type to JSON. 


Automatic Conformance 

Making one of your own types codable can be as easy as conforming it to Codable. if all 
of the type’s stored properties are themselves codable, the Swift compiler will 
automatically generate code that implements the Encodable and Decodable protocols. 
This Coordinate struct stores a GPS location: 

struct Coordinate: Codable { 
var latitude: Double 
var longitude: Double 
// Nothing to implement here 

} 

Because both stored properties are already codable, adopting the Codable protocol is 
enough to satisfy the compiler. Similarly, we can now write a Placemark struct that takes 
advantage of Coordinate’s Codable conformance: 


struct Placemark: Codable { 
var name: String 
var coordinate: Coordinate 

} 

The code the compiler synthesizes isn’t visible, but we’ll dissect it piece by piece a little 
later in this chapter. For now, treat the generated code like you would a default 
implementation for a protocol in the standard library, such as Sequence.drop(while:) — 
you get the default behavior for free, but you have the option of providing your own 
implementation. 

The only material difference between code generation and “normal” default 
implementations is that the latter are part of the standard library, whereas the logic for 
the Codable code synthesis lives in the compiler. Moving the code into the standard 
library would require more capable reflection APIs than Swift currently has, and even if 
those existed, runtime reflection would bring its own tradeoffs (e.g. reflection is typically 
slower). 

Nonetheless, shifting as much of the language definition as possible out of the compiler 
and into libraries remains a stated goal for Swift. Some day we’ll probably get a macro 
system that’s powerful enough to move the entire Codable system into the standard 
library, but that’s at least several years off. Until then, compiler code synthesis is a 
pragmatic solution to this problem. We’re already seeing more applications of it for the 
upcoming automatic Equatable and Hashable conformance . 


Encoding 

Swift ships with two built-in encoders, JSONEncoder and PropertyListEncoder (these are 
defined in Foundation and not in the standard library). In addition, codable types are 
compatible with Cocoa’s NSKeyedArchiver. We’ll focus on JSONEncoder because JSON is 
the most common format. 

Here’s how we can encode an array of Placemark values to JSON: 
let places = [ 

Placemark(name: ''Berlin'', coordinate: 

Coordinate(latitude: 52, longitude: 13)), 

Placemark(name: "Cape Town", coordinate: 

Coordinate(latitude: -34, longitude: 18)) 



] 


do { 

let encoder = JSONEncoderQ 

let jsonData = try encoder.encode(places) // 729 bytes 
let jsonString = String(decoding: jsonData, as: UTFS.self) 

/* 

[{"name":" Berlin"" coordinate"’.{"longitude" :T 3,"lat\tude":52}}, 

{"name":"Cape Town""coordinate"’.{"longitude":18 "latitude":-34}}] 

*/ 

} catch { 

print(error.localized Description) 

} 

The actual encoding step is exceedingly simple: create and (optionally) configure the 
encoder, and pass it the value to encode. The JSON encoder returns a collection of bytes 
in the form of a Data instance, which we then convert into a string for display. 

In addition to a property for conhguring the output formatting (pretty-printed and/or 
keys sorted lexicographically), JSON Encoder provides customization options for 
formatting dates (including ISO 8601 or Unix epoch timestamp) and Data values 
(e.g. Base64), as well as how exceptional floating-point values (inhnity and not a 
number) should be treated. These options always apply to the entire hierarchy of values 
being encoded, i.e. you can’t use them to specify that a Date in one type should follow a 
different encoding scheme than one in another type. If you need that kind of granularity, 
you have to write custom Codable implementations for the affected types. 

It’s worth noting that all of these configuration options are specific to JSON Encoder. 
Other encoders will have different options (or none at all). Even the encode(_:) method is 
encoder-specific and not dehned in any of the protocols. Other encoders might decide to 
return a String or even a URL to the encoded hie instead of a Data value. 

In fact, JSON Encoder doesn’t even conform to the Encoder protocol. Instead, it’s a 
wrapper around a private class named _JSONEncoder that implements the protocol and 
does the actual encoding work. It was designed in this way because the top-level 
encoder should provide an entirely different API (namely, a single method to start the 
encoding process) than the Encoder object that’s being passed to codable types during 
the encoding process. Separating these tasks cleanly means clients can only access the 
APIs that are appropriate in any given situation — for example, a codable type can’t 
reconfigure the encoder in the middle of the encoding process because the public 
configuration API is only exposed by the top-level encoder. 


Decoding 


The decoding counterpart for JSONEncoder is JSONDecoder. Decoding foiiows the same 
pattern as encoding: create a decoder and pass it something to decode. JSONDecoder 
expects a Data instance containing UTF-8-encoded JSON text, but as we just saw with 
encoders, other decoders may have different interfaces: 

do { 

let decoder = JSONDecoderQ 

let decoded = try decoder.decode([Placemark].self, from: jsonData) 

// [Berlin (lat: 52.0, Ion: 13.0), Cape Town (lat: -34.0, Ion: 18.0)] 
type(of: decoded) // Array<Placemark> 
decoded == places//true 
} catch { 

print(error.localized Description) 

} 

Notice that decoder.decode(_:from;) takes two arguments. In addition to the input data, 
we also have to specify the type we expect to get back (here it’s [Placemarkj.self). This 
allows for full compile-time type safety. The tedious conversion from weakly typed 
JSON data to the concrete data types we use in our code happens behind the scenes. 

Making the decoded type an explicit argument of the decoding method is a deliberate 
design choice. This wasn’t strictly necessary, as the compiler would’ve been able to infer 
the correct type automatically in many situations, but the Swift team decided that the 
increase in clarity and avoidance of ambiguity was more important than maximum 
conciseness. 

Even more so than during encoding, error handling is extremely important during 
decoding. There are so many things that can go wrong — from missing data (a required 
held is missing in the JSON input), to type mismatches (the server unexpectedly 
encodes numbers as strings), to fully corrupted data. Check out the documentation for 
the DecodingError type to see what other errors you can expect. 


The Encoding Process 


If using the Codable system is all you’re interested in and the default behavior works for 
you, you can stop reading now. But to understand how to customize the way types get 


encoded, we need to dig a little deeper. How does the encoding process work? What 
code does the compiler actually synthesize when we conform a type to Codable? 

When you initiate the encoding process, the encoder will call the encode(to: Encoder) 
method of the value that’s being encoded, passing itself as the argument. It’s then the 
value’s responsibility to encode itself into the encoder in any format it sees fit. 

In our example above, we pass an array of Placemark values to the JSON encoder: 
letjsonData = try encoder.encode(places) 

The encoder (or rather its private workhorse, _JSON Encoder) will now call 
places.encode(to: self). How does the array know how to encode itself in a format the 
encoder understands? 


Containers 

Let’s take a look at the Encoder protocol to see the interface an encoder presents to the 
value being encoded: 

/// J\ type that can encode values into a native format for external representation. 

public protocol Encoder { 

///The path of coding keys taken to get to this point in encoding. 
varcodingPath: [CodingKey] {get} 

///Any contextual information set by the user for encoding. 
var userinfo: [CodingUserInfoKey :Any] {get} 

/// Returns an encoding container appropriate for holding 

///multiple values keyed by the given key type. 

func container<Key: CodingKey>(keyedBy type; Key.Type) 

-> KeyedEncodingContainer<Key> 

/// Returns an encoding container appropriate for holding 
///multiple unkeyed values. 

func unkeyedContainerO -> UnkeyedEncodingContainer 
/// Returns an encoding container appropriate for holding 
///a single primitive value. 

func singleValueContainerQ -> SingleValueEncodingContainer 

} 

Ignoring codingPath and userinfo for a moment, it’s apparent that an Encoder is 
essentially a provider of encoding containers. A container is a sandboxed view into the 


encoder’s storage. By creating a new container for each vaiue that’s being encoded, the 
encoder can make sure the vaiues don’t overwrite each other’s data. 

There are three types of containers: 

-> Keyed containers encode key-vaiue pairs. Think of a keyed container as a 
speciai kind of dictionary. Keyed containers are hy far the most prevaient. 

The keys in a keyed encoding container are strongly typed, providing type safety 
and autocompletion. The encoder will eventually convert the keys to strings (or 
integers) when it writes its target format (such as JSON), but that’s hidden from 
client code. Changing the keys your type provides is the easiest way to customize 
how it encodes itself. We’ll see an example of this below. 

-> Unkeyed containers encode multiple values sequentially, omitting keys. Think 
of an array of encoded values. Because there are no keys to Identify a value, 
decoding containers must take care to decode values in the same order they were 
encoded. 

^ Single value containers encode a single value. You’d use this for types that are 
wholly defined by a single property. Examples include primitive types like Int or 
enums that are RawRepresentable as primitive values. 

For each of the three container types, there’s a protocol that defines the interface 
through which the container receives values to encode. Here’s the definition of 
SingleValueEncodingContainer: 

///k container that can support the storage and direct encoding of a single 
/// non-keyed value. 

public protocol SingleValueEncodingContainer { 

/// The path of coding keys taken to get to this point in encoding. 
varcodingPath: [CodingKey] {get} 

///Encodes a null value. 

mutating func encodeNilO throws 

/// Base types 

mutating func encode(_ value: Bool) throws 
mutating func encode(_ value: Int) throws 
mutating func encode(_ value: IntS) throws 
mutating func encode(_ value: Inti 6) throws 
mutating func encode(_ value: Int32) throws 
mutating func encode(_ value: Int64) throws 


mutating func encodeL value: UInt) throws 
mutating func encodeL value: Ulnt8) throws 
mutating func encodeL value: U Inti 6) throws 
mutating func encodeL value: Ulnt32) throws 
mutating func encodeL value: Ulnt64) throws 
mutating func encodeL value: Float) throws 
mutating func encodeL value: Double) throws 
mutating func encodeL value: String) throws 

mutating func encode<T: Encodable>L value:!) throws 

} 

As you can see, the protocol mainly declares a bunch of encodeL:) overloads for various 
types: Bool, String, and the integer and floating-point types. There’s also a variant for 
encoding a null value. Every encoder and decoder must support these primitive types, 
and all Encodable types must ultimately be reducible to one of these types. The Swift 
E volution proposal that introduced the Codable system says: 


These ... overloads give strong, static type guarantees about what is encodable 
(preventing accidental attempts to encode an invalid type), and provide a list 
of primitive types that are common to all encoders and decoders that users can 
rely on. 


Any value that isn’t one of the base types ends up in the generic encode<T: Encodable> 
overload, in it, the container will eventually call the argument’s encode(to: Encoder) 
method, and the entire process will start over one level down until only primitive types 
are left. But the container is free to treat types with special requirements differently. For 
instance, it’s at this point that _JSON Encoder checks if it’s encoding a Data value that 
must observe the configured encoding strategy, such as Base64 (the default behavior for 
Data is to encode itself as an unkeyed container of UIntS bytes). 

UnkeyedEncodingContainer and KeyedEncodingContainerProtocol have the same 
structure as SingleValueEncodingContainer, but they expose a few additional capabilities, 
such as creating nested containers. If you want to write an encoder and decoder for 
another data format, implementing these containers is most of the work. 







How a Value Encodes Itself 


Going back to our example, the top-level type we’re encoding is Array<Placemark>. An 
unkeyed container is a perfect match for an array (which is, after all, a sequential list of 
values), so the array asks the encoder for one. The array then iterates over its elements 
and tells the container to encode each one. Here’s how this process looks in code: 

extension Array: Encodable where Element: Encodable { 
public func encode(to encoder: Encoder) throws { 
var container = encoder.unkeyedContainerQ 
for element in self { 
try container.encode(element) 

} 

} 


( The actual code in the standard library is slightly longer and less elegant than this. The 
where Element: Encodable part doesn’t compile in Swift 4 because the compiler doesn’t 
support conditional protocol conformance yet. Runtime assertions and forced casts 
have to take its place.) 

The array elements are Placemark instances. We’ve seen that for non-primitive types, 
the container will continue calling each value’s encode(to:) method. 


The Synthesized Code 

This brings us to the code the compiler synthesizes for the Placemark struct when we 
add Codable conformance. Let’s walk through it step by step. 


Coding Keys 

The first thing the compiler generates is a private nested enum named CodingKeys: 

struct Placemark { 

//... 

private enum CodingKeys: CodingKey { 


case name 



case coordinate 


} 

} 

The enum contains one case for every stored property of the struct. The enum values are 
the keys for a keyed encoding container. Compared to string keys, these strongly typed 
keys are much safer and more convenient to use because the compiler will And typos. 
However, encoders must eventually be able to convert keys to strings or integers for 
storage. Handling these translations is the task of the CodingKey protocol: 

/// J\ type that can be used as a key for encoding and decoding. 
public protocol CodingKey { 

///The string to use in a named collection (e.g. a string-keyed dictionary). 
var stringValue: String {get} 

///The value to use in an integer-indexed collection 

///(e.g. an int-keyed dictionary). 

var intValue: Int? { get } 

init?(stringValue: String) 

init?(intValue: Int) 

} 

All keys must provide a string representation. Optionally, a key type can also provide a 
conversion to and from integers. Encoders can choose to use integer keys if that’s more 
efficient, but they are also free to ignore them and stick with string keys (as 
JSON Encoder does). The default compiler-synthesized code only produces string keys. 


The encode(to:) Method 

This is the code the compiler generates for the Placemark struct’s encode(to;) method: 

struct Placemark: Codable { 

// ,,, 

func encode(to encoder: Encoder) throws { 
var container = encoder.container(keyedBy: CodingKeys.self) 
try container.encode(name, forKey: .name) 
try container.encode(coordinate, forKey: .coordinate) 

} 

} 


The main difference to the array version is that Placemark encodes itself into a keyed 
container. A keyed container is the correct choice for all composite data types (structs 
and classes) with more than one property. Notice how the code passes CodingKeys.self 
to the encoder when it requests the keyed container. All subsequent encode commands 
into this container must specify a key of the same type. Since the key type is usually 
private to the type that’s being encoded, this design makes it nearly impossible to 
accidentally use another type’s coding keys when implementing this method manually. 

The end result of the encoding process is a tree of nested containers which the JSON 
encoder can translate into its target format: keyed containers become JSON objects 
({...}), unkeyed containers become JSON arrays ([... ]), and single value containers get 
converted to numbers, booleans, strings, or null, depending on their data type. 


The init(from:) Initializer 

When we call try decoder.decode([Placemark].self, from: jsonData), the decoder creates 
an instance of the type we passed in (here it’s [Placemark]) using the initializer dehned 
in Decodable. Like encoders, decoders manage a tree of decoding containers, which can 
be any of the three familiar kinds: keyed, unkeyed, or single value containers. 

Each value being decoded then walks recursively down the container hierarchy and 
initializes its properties with the values it decodes from its container. If at any step an 
error is thrown (e.g. because of a type mismatch or missing value), the entire process 
fails with an error. 

A typical decoding initializer implementation should look familiar to you. Here’s the 
one the compiler generates for Placemark: 

struct Placemark: Ccdable { 


init(from deccder: Deccder) throws { 
let container = try decoder.container(keyedBy: CodingKeys.self) 
name = try container.decode(String.self, forKey: .name) 
coordinate = try container.decode(Coordinate.self, forKey: .coordinate) 

} 


} 


Manual Conformance 


If your type has special requirements, you can always implement the Encodable and 
Decodable requirements yourself. What’s nice is that the automatic code synthesis isn’t 
an all-or-nothing thing — you can pick and choose what to override and take the rest 
from the compiler. 


Custom Coding Keys 

The easiest way to control how a type encodes itself is to write a custom CodingKeys 
enum (which doesn’t have to be an enum, by the way, although only enums get 
synthesized implementations for the CodingKey protocol). Providing custom coding 
keys is a very simple and declarative way of changing how a type is encoded. We can: 

^ rename fields in the encoded output by giving them an explicit string value, or 
^ skip Helds altogether by omitting their keys from the enum. 

To assign different names, we also have to give the enum an explicit raw value type of 
String. For example, this will map name to "label" in the JSON output while leaving the 
coordinate mapping unchanged: 

struct Placemark2: Codable { 
var name: String 
var coordinate: Coordinate 

private enum CodingKeys: String, CodingKey { 
case name = "label" 
case coordinate 

} 

//Compiler-synthesized encode and decode methods 
// wilt use overridden CodingKeys 

} 

And this will skip the placemark’s name and only encode the GPS coordinates because 
we didn’t include the name key in the enum: 

struct PlacemarkS: Codable { 
var name: String = "(Unknown)" 


var coordinate: Coordinate 


private enum CodingKeys: CodingKey { 
case coordinate 

} 

} 

Notice the default value we had to assign to the name property. Without It, code 
generation for Decodable will fall when the compiler detects that It can’t assign a value 
to name In the Initializer. 

Skipping properties during encoding can be useful for transient values that can easily be 
recomputed or aren’t Important to store, such as caches or memolzed expensive 
computations. The compiler Is smart enough to Alter out lazy properties on Its own, but 
If you use normal stored properties for transient values, this Is how you can do It 
yourself. 


Custom encode(to:) and init(from:) Implementations 

If you need more control, there’s always the option to Implement encode(to:) and/or 
init(from:) yourself. As an example, consider how the decoder deals with optional values. 
JSON Encoder and JSON Decoder can handle optlonals out of the box. That Is, If a 
property of the target type Is optional, the decoder will correctly skip It If no 
corresponding value exists In the Input data. 

Here’s an alternative dehnltlon of the Placemark type where the coordinate property Is 
optional: 

struct PlacemarkA: Codable { 
var name: String 
var coordinate: Coordinate? 

} 

Now our server can send us JSON data where the "coordinate" held Is missing: 

let validJSONInput = """ 

[ 

{"name" : "Berlin"}, 

{"name" : "Cape Town"} 


] 


When we ask JSONDecoder to decode this input into an array of Placemark4 vaiues, it’ii 
automaticaiiy set the coordinate values to nil. So far so good. 

However, JSONDecoder can be quite picky about the structure of the input data, and 
even small deviations from the expected format can trigger a decoding error. Now 
suppose the server is configured to send an empty JSON object to signify a missing 
optional value, so it sends this piece of JSON: 

letinvalidJSONInput = . 

[ 

{ 

''name" : "Berlin", 

"coordinate": {} 

} 

] 

II II II 


When we try to decode this, the decoder, expecting the "latitude" and "longitude" fields 
inside the coordinate object, trips over the empty object and fails with a .keyNotFound 
error: 

do { 

let inputData = invalidJSONInput.data(using: .utf8)! 
let decoder = JSONDecoderQ 

let decoded = try decoder.decode([Placemark4].self, from: inputData) 

} catch { 

print(error.localized Description) 

// The data couldn’t be read because it is missing. 

} 

To make this work, we can override the Decodable initializer and explicitly catch the 
error we expect: 

struct Placemark4: Codable { 
var name: String 
var coordinate: Coordinate? 


// encode(to:) is still synthesized by compiler 


init(from decoder: Decoder) throws { 
let container = try decoder.container(keyedBy: CodingKeys. self) 
self.name = try container.decode(String.self, forKey: .name) 

do { 

self.coordinate = try container.decodelfPresent(Coordinate.self, 
forKey: .coordinate) 

} catch DecodingError.keyNotFound { 
self.coordinate = nil 

} 

} 


Now the decoder can successfully decode the faulty JSON: 

do { 

let inputData = invalidJSONInput.data(using: .utf8)! 
let decoder = JSONDecoderQ 

let decoded = try decoder.decode([Placemark4].self, from: inputData) 
decoded /[Berlin (nil)] 

} catch { 

print(error.localized Description) 

} 

Note that other errors, such as fully corrupted Input data or any problem with the name 
held, will still throw. 

This sort of customization is a nice option if only one or two types are affected, but it 
doesn’t scale well. If a type has dozens of properties, you’ll have to write manual code for 
each field, even if you only need to customize a single one. You might also want to read 
Dave Lyon’s article on the topic . Dave came up with a generic protocol-based solution 
for exactly this issue. And if you have control over the input, it’s always better to fix the 
problem at the source (make the server send valid JSON) rather than doctor with 
malformed data at a later stage. 


Common Coding Tasks 


In this section, we’d like to discuss some common tasks you might want to solve with the 
Codable system, along with potential problems you might run into. 



Making Types You Don’t Own Codable 


Suppose we want to replace our Coordinate type with CLLocationCoordinate2D from the 
Core Location framework. CLLocationCoordinate2D has the exact same structure as 
Coordinate, so it makes sense not to reinvent the wheel. 

The problem is that CLLocationCoordinate2D doesn’t conform to Codable. As a result, 
the compiler will now (correctly) complain that it can’t synthesize the Codable 
conformance for PlacemarkS any longer because one of its properties isn’t Codable itself: 

import CoreLocation 

struct Placemarkb: Codable { 
var name: String 

var coordinate: CLLocationCoordinate2D 

} 

// error: cannot automatically synthesize 'Decodable'/'Enccdable' 

//because 'CLLocationCoordinate2D' does not conform 

Can we make CLLocationCoordinate2D codable despite the fact that the type is defined in 
another module? Adding the missing conformance in an extension produces an error: 

extension CLLocationCoordinate2D: Codable {} 

//error: implementation of 'Decodable'/'Encodable' cannot be 
// automatically synthesized in an extension yet 

Swift 4.0 wiil only generate code for conformances that are specified on the type 
definition itself — we’d have to implement the protocols manually. But even if that 
limitation didn’t exist (the Swift team plans to lift it, at least for extensions in the same 
hie or moduie), retroactively adding Codable conformance to a type we don’t own is 
probably not a good idea. What if Apple decides to provide the conformance itself in a 
future SDK version? It’s likely that Apple’s implementation won’t be compatible with 
ours, which means values encoded with our version wouldn’t decode with Apple’s code, 
and vice versa. This is a problem because a decoder can’t know which implementation it 
should use — it only sees that it’s supposed to decode a value of type 
CLLocationCoordinate2D. 

Itai Ferber, a developer at Apple who wrote large chunks of the Codable system, gives 
this advice: 



I would actually take this a step further and recommend that any time you 
intend to extend someone else’s type with Encodable or Decodable, you should 
almost certainly write a wrapper struct for it instead, unless you have 
reasonable guarantees that the type will never attempt to conform to these 
protocols on its own. 


We’ll see an example of this in the next section. As for our current problem, let’s go with 
a slightly different (but equally safe) solution: we’ll provide our own Codable 
implementation for PlacemarkS, where we encode the latitude and longitude values 
directly. This effectively hides the existence of the CLLocationCoordinate2D type from 
the encoders and decoders; from their perspective. It looks as if the latitude and 
longitude properties were defined directly on PlacemarkS: 

extension PlacemarkS { 

private enum CodingKeys: String, CodingKey { 
case name 
case latitude = "lat" 
case longitude = "Ion" 

} 

func encode(to encoder: Encoder) throws { 
var container = encoder.container(keyedBy; CodingKeys. self) 
try container.encode(name, forKey: .name) 

// Encode latitude and longitude separately 

try container.encode(coordinate.latitude, forKey: .latitude) 

try container.encode(coordinate.longitude, forKey: .longitude) 

} 

init(from decoder: Decoder) throws { 
let container = try decoder.container(keyedBy: CodingKeys. self) 
self.name = try container.decode(String.self, forKey: .name) 

// Reconstruct CLLocationCoordinate2D from lat/lon 
self.coordinate = CLLocationCoordinate2D( 
latitude: try container.decode(Double.self, forKey: .latitude), 
longitude: try container.decode(Double.self, forKey: .longitude) 

) 

} 



This example provides a good idea of the boilerplate code we’d have to write for every 
type if the compiler didn’t generate it for us (and the synthesized implementation for 
the CodingKey protocol is still missing here). 


Nested Containers 

Alternatively, we could’ve used a nested container to encode the coordinates. 

KeyedDecodingContainer has a method named nestedContainer(keyedBy:forKey:) that 
creates a separate keyed container (with a separate coding key type) and stores it under 
the provided key. We’d add a second enum for the nested keys and encode the latitude 
and longitude values Into the nested container (we’re only showing the Encodable 
implementation here; Decodable follows the same pattern): 

struct Placemark6: Encodable { 

var name: String 

var coordinate: CLLocationCoordinate2D 

private enum CodingKeys: CodingKey { 
case name 
case coordinate 

} 

//The coding keys for the nested container 

private enum CoordinateCodingKeys: CodingKey { 
case latitude 
case longitude 

} 

func encode(to encoder: Encoder) throws { 
var container = encoder.container(keyedBy: CodingKeys. self) 
try container.encode(name, forKey: .name) 
var coordinateContainer = container.nestedContainer( 
keyedBy: CoordinateCodingKeys. self, forKey: .coordinate) 
try coordinateContainer.encode(coordinate.latitude, forKey: .latitude) 
try coordinateContainer.encode(coordinate.longitude, forKey: .longitude) 

} 


With this approach, we wouid have effectiveiy recreated the way the Coordinate type 
encodes itself inside our original Placemark struct, but without exposing the nested type 
to the Codable system at all. The resulting JSON is identical in both cases. 


The Computed Property Workaround 

As you can see, the amount of code we have to write for both alternatives is significant. 
For this particular example, we recommend a different approach, and that’s to stick with 
our custom Coordinate struct for storage and Codable conformance, and expose the 
CLLocationCoordinate2D to clients as a computed property. Because the private 
_coordinate property is codable, we get the Codable conformance for free; all we have to 
do is rename its key in the CodingKeys enum. And the client-facing coordinate property 
has the type our clients require, but the Codable system will ignore it because it’s a 
computed property: 

struct Placemark?: Codable { 
var name: String 

private var _coordinate: Coordinate 
var coordinate: CLLocationCoordinate2D { 
get{ 

return CLLocationCoordinate2D(latitude: _coordinate.latitude, 
longitude: _coordinate. longitude) 

} 

set { 

_coordinate = Coordinateflatitude: newValue.latitude, 
longitude: newValue.longitude) 

} 

} 

private enum CodingKeys: String, CodingKey { 
case name 

case _coordinate = "coordinate" 

} 


This approach works well in this case because CLLocationCoordinate2D is such a simple 
type, and translating between it and our custom type is easy. 


Making Classes Codable 


We saw in the previous section that it’s possibie (if not advisabie) to retroactiveiy 
conform any vaiue type to Codable. However, this isn’t the case for non-hnai ciasses. 

As a generai ruie, the Codable system works just fine with ciasses, but the potentiai 
existence of subciasses adds another ievei of compiexity. What happens if we try to 
conform, say, UlColor to Decodable? (We’re ignoring Encodable for the moment because 
it’s not relevant for this discussion; we can add it later.) We got this example from a 
message by Jordan Rose on the swift-evolution mailing list. 

A custom Decodable implementation for UlColor might look like this: 

extension UlColor: Decodable { 
private enum CodingKeys: CodingKey { 
case red 
case green 
case blue 
case alpha 

} 

// Error: initializer requirement 'init(from:)' can only be satisfied 
//by a 'required' initializer in the definition of non-final class 'UlColor' 

//etc. 

public init(from decoder: Decoder) throws { 
let container = try decoder.container(keyedBy: CodingKeys. self) 
let red = try container.decode(CGFloat.self, forKey: .red) 
let green = try container.decode(CGFloat.self, forKey: .green) 
let blue = try container.decode(CGFloat.self, forKey: .blue) 
let alpha = try container.decode(CGFloat.self, forKey: .alpha) 
self.init(red: red, green: green, blue: blue, alpha: alpha) 

} 

} 

This code fails to compile, with several errors that ultimately boil down to one 
unsolvable conflict: only required initializers can satisfy protocol requirements, and 
required initializers may not be added in extensions; they must be declared directly in 
the class definition. 

A required initializer (marked with the required keyword) indicates an Initializer that 
every subclass must Implement. The rule that initializers defined in protocols must be 



required ensures that they, like all protocol requirements, can he invoked dynamically 
on subclasses. The compiler must guarantee that code like this works: 

func decodeDynamicL colorType: UlColor.Type, 
from decoder: Decoder) throws -> UlColor { 
return try colorType.init(from: decoder) 

} 

let color = decodeDynamic(SomeUIColorSubclass.self, from: someDecoder) 

For this dynamic dispatch to work, the compiler must create an entry for the initializer 
in the class’s dispatch table. This table of the class’s non-hnal methods is created with a 
fixed size when the class definition is compiled; extensions can’t add entries 
retroactively. This is why the required initializer is only allowed in the class definition. 

Long story short: it’s impossible to retroactively conform a non-final class to Codabie in 
Swift 4. In the mailing list message we referenced above, Jordan Rose discusses a 
number of scenarios detailing how Swift could make this work in the future — from 
allowing a required initializer to be final (then it wouldn’t need an entry in the dispatch 
table), to adding runtime checks that would trap if a subclass didn’t provide the 
designated initializer that the required initializer calls. 

But even then, we’d still have to deal with the fact that adding Codabie conformance to 
types you don’t own is problematic. As in the previous section, the recommended 
approach is to write a wrapper struct for UlColor and make that codabie. 

Let’s start by writing a small extension that makes it easier to extract the red, green, blue, 
and alpha components from a UlColor value. The existing getRed(_:green:blue:alpha:) 
method uses pointers to pass the results back to the caller because Objective-C doesn’t 
support tuples as return types. We can do better in Swift: 

extension UlColor { 

var rgba: (red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)? { 
var red: CGFloat = 0.0 
var green: CGFloat = 0.0 
var blue: CGFloat = 0.0 
var alpha: CGFloat = 0.0 

if getRed(&red, green: Stgreen, blue: &blue, alpha: Stalpha) { 
return (red: red, green: green, blue: blue, alpha: alpha) 

} else { 
return nil 

} 


} 


We’ll use the rgba property In our encode(to:) implementation. Notice that the type of 
rgba is an optional tuple because not all UlColor instances can be represented as RGBA 
components. If someone tries to encode a color that isn’t convertible to RGBA (e.g. a 
color based on a pattern image), we’ll throw an encoding error. 

Here’s the complete implementation for our UlColor.CodabieWrapper struct (we 
namespaced the struct inside UlColor to make the relationship between the two clear): 

extension UlColor { 
struct CodabieWrapper: Codable { 

var value: UlColor 

init(_ value: UlColor) { 
self.value = value 

} 

enum CodingKeys: CodingKey { 
case red 
case green 
case blue 
case alpha 

} 

func encode(to encoder: Encoder) throws { 

// Throw error if color isn't convertible to RGBA 
guard let (red, green, blue, alpha) = value.rgba else { 
let errorContext = EncodingError.Context( 
codingPath: encoder.codingPath, 
debugDescription: 

"Unsupported color format: \(value)" 

) 

throw EncodingError.invalidValue(value, errorContext) 

} 

var container = encoder.container(keyedBy: CodingKeys. self) 
try container.encode(red, forKey: .red) 
try container.encode(green, forKey: .green) 
try container.encode(blue, forKey: .blue) 
try container.encode(alpha, forKey: .alpha) 


} 


init(from decoder: Decoder) throws { 
let container = try decoder.container(keyedBy: CodingKeys. self) 
let red = try container.decode(CGFloat.self, forKey: .red) 
let green = try container.decode(CGFloat.self, forKey: .green) 
let blue = try container.decode(CGFloat. self, forKey: .blue) 
let alpha = try container.decode(CGFloat.self, forKey: .alpha) 
self.value = UlColor(red: red, green: green, blue: blue, alpha: alpha) 

} 

} 

} 

We should note that this implementation is somewhat imperfect because it converts all 
colors to an RGB color space during encoding. When you later decode such a value, 
you’ll always get back an RGB color, even if the color you originally encoded was in a 
grayscale color space, for example. Since there’s no public UlColor API to identify the 
color space a color is in, a better implementation would have to drop down to the 
underlying CGColor to identify the color’s color space model (e.g. RGB or grayscale) and 
then encode both the color space model and the components that make sense for the 
color space in question. On decoding, you’d then have to decode the color space model 
first before you’d know what other keys you could expect to And in the decoding 
container. 

The big downside of the wrapper struct approach is that you’ll have to manually convert 
between UlColor and the wrapper before encoding and after decoding. Suppose you 
want to encode an array of UlColor values: 

let colors: [UlColor] = [ 

.red, 

.white, 

.init(displayP3Red: 0.5, green: 0.4, blue: 1.0, alpha: 0.8), 

.init(hue: 0.6, saturation: 1.0, brightness: 0.8, alpha: 0.9), 

] 

You’ll have to map the array to UlColor.CodableWrapper before you can pass it to an 
encoder: 


let codableColors = colors.map(UlColor.CodableWrapper.init) 


Moreover, any type that stores a UlColor will no longer participate in automatic code 
synthesis. Dehning a type like the following produces an error because UlColor isn’t 
Codable: 

// error: cannot automatically synthesize 'Encodable'/'Decodable' 
struct ColoredRect: Codable { 
var rect: CGRect 
var color: UlColor 

} 

How do we fix this with the least amount of code? As in the previous section, we’ll add a 
private property of type UlColor.CodableWrapper that acts as storage for the color value, 
and we’ll make color a computed property that forwards to _color in its accessors. We’ll 
also need to add an initializer. Lastly, we’ll provide our own coding keys enum to change 
the key used to encode the color value from the default "_color" to "color" (this step is 
optional): 

struct ColoredRect: Codable { 
var rect: CGRect 
//Storage for color 

private var _color: UlColor.CodableWrapper 
var color: UlColor { 
get { return _color.value} 
set {_color.value = newValue} 

} 

init(rect: CGRect, color: UlColor) { 
self, rect = rect 

self._color = UlColor.CodableWrapper(color) 

} 

private enum CodingKeys: String, CodingKey { 
case rect 

case _color = "color" 

} 


Encoding an array of ColoredRect values produces this JSON output: 

let rects = [ColoredRect(rect: CGRect(x: 10, y: 20, width: 100, height: 200), 
color: .yellow)] 


do { 

let encoder = JSONEncoderQ 

letjsonData = try encoder.encode(rects) 

let jsonString = String(decoding: jsonData, as: UTFS.self) 

// [{"color" :{"red":l /’alpha": 1 "blue" :0,"green'':1},"rect'':[[10,20], [100,200]]}] 

} catch { 

print(error.localized Description) 

} 


Making Enums Codable 

The compiler can synthesize Codable conformance for RawRepresentable enums whose 
RawValue type is one of the “native” codable types, namely Bool, String, Float, Double, or 
one of the integer types. For other enums, such as those with associated values, you 
need to implement the requirements manually. 

Let’s conform the Either enum to Codable. Either is a very common type for modeling a 
value that can be either some value of a generic type A or some value of another type B. 
Here’s the full implementation: 

enum Either<A: Codable, B: Codable>: Codable { 
case left(A) 
case right(B) 

private enum CodingKeys: CodingKey { 
case left 
case right 

} 

func encode(to encoder: Encoder) throws { 
var container = encoder.container(keyed By: CodingKeys. self) 
switch self { 
case .left(let value): 

try container.encode(value, forKey: .left) 
case .right(let value): 
try container.encode(value, forKey: .right) 

} 

} 


init(from decoder: Decoder) throws { 


let container = try decoder.container(keyedBy: CodingKeys. self) 
if let leftValue = try container.decodelfPresent(A.self, forKey: .left) { 
self = .left(leftValue) 

} else { 

let rightValue = try container.decode(B. self, forKey: .right) 
self = .right(rightValue) 

} 

} 


In encode(to:), we check whether we have a left or right value and encode it under the 
corresponding key. Similarly, the init(from:) initializer uses the container’s 
decodelfPresent method to check if the container has a value for the left key. If not, it 
unconditionally decodes the right key, because one of the two keys must be present. 

Ideally, we’d dehne the type as enum Either<A, B> — without any constraints on the 
generic type parameters — and then conditionally add the Codable conformance when 
both generic types are codable themselves, i.e. add 

extension Either: Codable where A: Codable, B: Codable. Unfortunately, the compiler 
doesn’t support conditional conformances yet. We went for the easiest workaround, and 
that’s to add the constraint directly to the type dehnition. This is good enough for an 
example; in production code, however, you probably can’t afford to make Either 
incompatible with all non-codable payloads, so you’d have to resort to runtime checks. 
Array and other standard library types do this too. 

Encoding and decoding a collection of values should be familiar by now. Let’s use 
PropertyListEncoder and PropertyListDecoder for a change: 

let values: [EithertString, int>] = [ 

.left(" Forty-two"), 

.right(42) 

] 

do { 

let encoder = PropertyListEncoderQ 

encoder.outputFormat = .xml 

let xmlData = try encoder.encode(values) 

let xmlString = String(decoding: xmlData, as: UTFS.self) 

/* 

<?xmt version = "l.0" encoding="UTF-8"?> 

<1D0CTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 



"http://www.apple.eom/DTDs/PropertyList-l.0.dtd"> 

<plistversion="1.0"> 

<array> 

<dict> 

<key>left</key> 

<string>Forty-two</string> 

</dict> 

<dict> 

<key>right</key> 

<integer>42</integer> 

</dict> 

</array> 

</pUst> 

*/ 


let decoder = PropertyListDecoderO 

let decoded = try decoder.decode([Either<String, lnt>].self, from: xmlData) 

/* 

[EithertSwift.String, Swift.Int>.ieft("Forty-two"), 

Either<Swift.String, Swift. Int>.right(42)] 

*/ 

} catch { 

print(error.localized Description) 

} 


Decoding Polymorphic Collections 

We’ve seen that decoders require us to pass in the concrete type of the value that’s being 
decoded. This makes intuitive sense: the decoder needs a concrete type to figure out 
which initializer to call, and since the encoded data typically doesn’t contain type 
information, the type must be provided by the caller. A consequence of this focus on 
strong typing is that there’s no polymorphism in the decode step. 

Suppose we want to encode an array of views, where the actual instances are UI View 
subclasses such as UI Label or UllmageView: 

let views: [UlView] = [label, imageView, button] 

(Let’s assume for a moment that UlView and all its subclasses conform to Codable, which 
they currently don’t.) 


If we’d encode this array and then decode it again, it wouidn’t come out in identicai form 
— the concrete types of the array eiements wouidn’t survive. The decoder wouid oniy 
produce piain UlView objects because aii it knows is that the type of the decoded data 
must be [UlView].self. 

So how can we encode such a coiiection of poiymorphic objects? The best option is to 
dehne an enum with one case per subciass we want to support. The payioads of the 
enum cases store the actuai objects: 

enum View { 
case view(UIView) 
case label(UILabel) 
case imageView(UllmageView) 

//.,. 

} 

We then have to manuaiiy write a Codable impiementation that foiiows a pattern simiiar 
to the Either enum in the previous section: 

-> During encoding, switch over aii cases to Hgure out which type of object we need 
to encode. Then encode the object’s type and the object itseif under separate 
keys. 

-> During decoding, decode the type information first and seiect the concrete type 
to initiaiize based on that. 

Finaiiy, we shouid write two convenience functions for wrapping a UlView in a View 
vaiue, and vice versa. That way, passing the source array to the encoder and getting it 
from the decoder oniy takes a singie map. 

Observe that this isn’t a dynamic soiution; we’ii have to manuaiiy update the View enum 
every time we want to support another subciass. This is inconvenient, but it does make 
sense that we’re forced to expiicitiy name every type our code can accept from a decoder. 
Anything eise wouid be a potentiai security risk, because an attacker couid use a 
manipuiated archive to instantiate unknown objects in our program. 


Recap 


The abiiity to seamiessiy convert between your program’s native types and common 
data formats with minimai code — at ieast for the common case — is a very weicome 


addition to Swift. The Codable system becomes even more powerful if you can use Swift 
on both client and server: using the same types everywhere ensures all platforms will 
produce compatible encoding formats. Overriding the default behavior is always 
possible, if sometimes inconvenient when you need to handle non-Codable types you 
haven’t dehned yourself. The Swift team is already exploring more customization 
options , such as the ability to rewrite keys from camelCase to snake_case without 
having to touch every single type. 

The system shines when you use it for the task it was designed for — working with 
uniform data in a known format in a fully type-safe manner. Swift does everything it can 
to hide the loosely typed dictionary-like data you’d get from a traditional JSON parser. 

In the rare cases where you’d rather work with a [String: Any] dictionary (maybe because 
you don’t know the exact data format), don’t try to intertwine the two worlds 
unnecessarily. The old-school method via JSONSerialization still exists. 

We only discussed traditional archiving tasks in this chapter, but it’s worth thinking 
outside the box to find other applications that can proht from a standardized way to 
reduce values to primitive data and vice versa. For example, you could write an encoder 
t hat computes a hash value from the encoded data and use that to automatically 
conform codable types to Hashable. This effectively uses the Codable system as a 
replacement for reflection. Or you could write a decoder that can produce random 
v alues for each of the primitive data types and use that to generate randomized test data 


for your unit tests. 








Functions 




To open this chapter, let’s recap some main points regarding functions. If you’re already 
very familiar with first-class functions, feel free to skip ahead to the next section. But if 
you’re even slightly hazy, skim through what’s below. 

To understand functions and closures in Swift, you really need to understand three 
things, in roughly this order of importance: 

1. Functions can be assigned to variables and passed in and out of other functions 
as arguments, just as an Int or a String can be. 

2. Functions can capture variables that exist outside of their local scope. 

3. There are two ways of creating functions — either with the func keyword, or with 
{}. Swift calls the latter closure expressions. 

Sometimes people new to the topic of closures come at it in reverse order and maybe 
miss one of these points, or conflate the terms closure and closure expression — and this 
can cause a lot of confusion. It’s a three-legged stool, and if you miss one of the three 
points above, you’ll fall over when you try to sit down. 


1. Functions can be assigned to variables and passed in and out of 
other functions as arguments. 

In Swift, as in many modern languages, functions are referred to as “first-class objects.’’ 
You can assign functions to variabies, and you can pass them in and out of other 
functions to be called later. 

This is the most important thing to understand. “Getting” this for functional 
programming is akin to “getting” pointers in C. If you don’t quite grasp this part, 
everything else will just be noise. 

Let’s start with a function that simpiy prints an integer: 

func printintji: Int) { 
printC'you passed \(i)'') 

} 

To assign the function to a variabie, funVar, we just use the function name as the value. 
Note the absence of parentheses after the function name: 


let funVar = printint 


Now we can call the printl nt function using the f u nVar variable. Note the use of 
parentheses after the variable name: 

funVar(2) //you passed 2 

It’s also noteworthy that we must not include an argument label in the funVar call, 
whereas printint calls require the argument label, as in printlnt(i: 2). Swift only allows 
a rgument labels In function declarations; the labels aren’t included in a function’s type. 
This means that you currently can’t assign argument labels to a variable of a function 
type, though this will likely change in a future Swift version . 

We can also write a function that takes a function as an argument: 

func useFunction(function: (Int) ->()){ 
function(3) 

} 

useFunction(function: printint) //you passed 3 
useFunction(function: funVar) //you passed 3 

Why is being able to treat functions like this such a big deal? Because it allows you to 
easily write “higher-order” functions, which take functions as arguments and apply 
them in useful ways, as we saw in the chapter on built-in collections. 

Functions can also return other functions: 

func returnFuncO -> (Int) -> String { 
func innerFunc(i: Int) -> String { 
return "you passed \(i)" 

} 

return innerFunc 

} 

let myFunc = returnFuncO 
nnyFunc(3) //you passed 3 





2. Functions can capture variables that exist outside of their local 
scope. 

When a function references variables outside the function’s scope, those variables are 
captured and stick around after they would otherwise fall out of scope and be destroyed. 

To see this, let’s revisit our returnFunc function but add a counter that increases each 
time we call it: 

func counterFuncO -> (Int) -> String { 
var counter = 0 

func innerFunc(i: Int) -> String { 
counter+=i // counter is captured 
return "running total: \(counter)'' 

} 

return innerFunc 

} 

Normally counter, being a local variable of counterFunc, would go out of scope just after 
the return statement, and it’d be destroyed. Instead, because it’s captured by innerFunc, 
the Swift runtime will keep it alive until the function that captured it gets destroyed. As 
we discussed in structs and classes, cou nter will exist on the heap rather than on the 
stack. We can call the inner function multiple times, and we see that the running total 
increases: 

let f = counterFuncO 
f(3) // running total: 3 
f(4) // running total: 7 

If we call counterFu nc() again, a fresh counter variable will be created and captured: 

let g = counterFuncO 
g(2) // running total: 2 
g(2) // running total: 4 

This doesn’t affect our hrst function, which still has its own captured version of counter: 
f(2) // running total: 9 


Think of these functions combined with their captured variables as similar to instances 
of classes with a single method (the function) and some member variables (the captured 
variables). 

In programming terminology, a combination of a function and an environment of 
captured variables is called a closure. So f and g above are examples of closures, because 
they capture and use a non-local variable (counter) that was declared outside of them. 


3. Functions can be declared using the {} syntax for closure 
expressions. 

In Swift, you can define functions in two ways. One is with the func keyword. The other 
way is to use a closure expression. Consider this simple function to double a number: 

func doubler(i: Int) -> Int { 
return i * 2 

} 

[1,2, 3,4].map(doubler) ///i, 4, 6, 8] 

And here’s the same function written using the closure expression syntax. Just like 
before, we can pass it to map: 

let doublerAlt = {(i: Int) -> Int in return i*2} 

[1,2, 3,4].map(doublerAlt) ///'2,4, 6, 8] 

Functions declared as closure expressions can be thought of as function literals in the 
same way that 1 and "hello" are integer and string literals. They’re also anonymous — 
they aren’t named, unlike with the func keyword. The only way they can be used is to 
assign them to a variable when they’re created (as we do here with doubler), or to pass 
them to another function or method. 


There’s a third way anonymous functions can be used: you can call a function 
directly in line as part of the same expression that defines it. This can be useful 
for defining properties whose initialization requires more than one line. We’ll 
see an example of this below in the section on lazy properties. 


The doubler declared using the closure expression, and the one declared earlier using 
the func keyword, are completely equivalent, apart from the differences in their 



handling of argument labels we mentioned above. They even exist in the same 
“namespace,” unlike in some languages. 

Why is the {} syntax useful then? Why not just use func every time? Well, it can be a lot 
more compact, especially when writing quick functions to pass into other functions, 
such as map. Here’s our doubler map example written in a much shorter form: 

[1,2, 3].map {$0*2}//[2,4,6] 

This looks very different because we’ve leveraged several features of Swift to make code 
more concise. Here they are one by one: 

1. If you’re passing the closure in as an argument and that’s all you need it for, 
there’s no need to store it in a local variable first. Think of this like passing in a 
numeric expression, such as 5*i, to a function that takes an I nt as a parameter. 

2. If the compiler can infer a type from the context, you don’t need to specify it. In 
our example, the function passed to map takes an Int (Inferred from the type of 
the array elements) and returns an I nt (inferred from the type of the 
multiplication expression). 

3. If the closure expression’s body contains just a single expression, it’ll 
automatically return the value of the expression, and you can leave off the return. 

4. Swift automatically provides shorthand names for the arguments to the function 
— $0 for the first, $1 for the second, etc. 

5. If the last argument to a function is a closure expression, you can move the 
expression outside the parentheses of the function call. This trailing closure 
syntax is nice if you have a multi-line closure expression, as it more closely 
resembles a regular function definition or other block statement such as if expr {}. 

6. Finally, if a function has no arguments other than a closure expression, you can 
leave off the parentheses after the function name altogether. 

Using each of these rules, we can boil down the expression below to the form shown 
above: 

[1,2, 3].map( {(i: Int) -> Int in return 1*2}) 

[1,2, 3].map( {I in return i * 2}) 

[1,2, 3].map( {i in i * 2}) 

[1.2.3] .map({$0*2}) 

[1.2.3] .map(){$0*2} 


[1,2,3].map{$0*2} 


If you’re new to Swift’s syntax, and to functional programming in generai, these compact 
function deciarations might seem daunting at first. But as you get more comfortahle 
with the syntax and the functionai programming styie, they’ii start to feet more naturai, 
and you’ii be gratefui for the ability to remove the clutter so you can see more clearly 
what the code is doing. Once you get used to reading code written like this, it’ll be much 
clearer to you at a glance than the equivalent code written with a conventional for loop. 

Sometimes, Swift needs a helping hand with inferring the types. And sometimes, you 
may get something wrong and the types aren’t what you think they should be. If ever 
you get a mysterious error when trying to supply a closure expression, it’s a good idea to 
write out the full form (first version above), complete with types. In many cases, that will 
help clear up where things are going wrong. Once you have the long form compiling, 
take the types out again one by one until the compiler complains. And if the error was 
yours, you’ll have hxed your code in the process. 

Swift will also insist you be more explicit sometimes. For example, you can’t completely 
ignore input parameters. Suppose you wanted an array of random numbers. A quick 
way to do this is to map a range with a function that just generates random numbers. But 
you must supply an argument nonetheless. You can use _ in such a case to indicate to 
the compiler that you acknowledge there’s an argument but that you don’t care what it 
is: 

(0..<3).map{_in arc4random() }//f3279537427, 1028964218,2788826702] 

When you need to explicitly type the variables, you don’t have to do it inside the closure 
expression. For example, try dehning isEven without any types: 

let isEven = {$0%2==0} 

Above, the type of isEven is inferred to be (Int) -> Bool in the same way that let i = 1 is 
inferred to be I nt — because I nt is the default type for integer literals. 


This is because of a typealias, IntegerLiteralType, in the standard library: 

protocol ExpressibleByIntegerLiteral { 
associatedtype IntegerLiteralType 
///Create an instance initialized to 'value'. 



init(integerLiteral value: Self.IntegerLiteralType) 

} 

/// The default type for an otherwise unconstrained integer literal. 
typealias IntegerLiteralType = Int 


If you were to define your own typealias, it would override the default one and 
change this behavior: 

typealias IntegerLiteralType = Ulnt32 
let i = 1 //i will be of type Ulnt32. 


This is almost certainly a bad idea. 


If, however, you needed a version of isEven for a different type, you could type the 
argument and return value inside the closure expression: 

let isEvenAlt = {(i: IntS) -> Bool in i % 2 == 0} 

But you could also supply the context from outside the closure: 

let isEvenAlt2: (IntS) -> Bool = {$0 % 2 == 0} 
let IsEvenAltS = {$0 % 2 == 0} as (IntS) -> Bool 

Since closure expressions are most commonly used in some context of existing input or 
output types, adding an explicit type isn’t often necessary, but it’s useful to know. 

Of course, it would’ve been much better to define a generic version of isEven that works 
on any Integer as a computed property: 

extension Binaryinteger { 
var isEven: Bool { return self % 2 == 0} 

} 

Alternatively, we could have chosen to define an isEven variant for all Integer types as a 
free function: 


func isEven<T: Binarylnteger>(_ i:T) -> Bool { 



return i % 2 = = 0 


} 

If you want to assign that free function to a variable, this is also when you’d have to lock 
down which specific types it’s operating on. A variable can’t hold a generic function — 
only a specific one: 

let intSisEven: (Int8) -> Bool = isEven 

One final point on naming. It’s important to keep in mind that functions declared with 
fu no can be closures, just like ones declared with {}. Remember, a closure is a function 
combined with any captured variables. While functions created with {} are called closure 
expressions, people often refer to this syntax as just closures. But don’t get confused and 
think that functions declared with the closure expression syntax are different from other 
functions — they aren’t. They’re both functions, and they can both be closures. 


Flexibility through Functions 

In the built-in collections chapter, we talked about parameterizing behavior by passing 
functions as arguments. Let’s look at another example of this: sorting. 

Sorting a collection in Swift is simple: 

let myArray = [3,1,2] 
myArray.sortedO2, 3] 

There are really four sort methods: the non-mutating variant sorted(by:), and the 
mutating sort(by:), times two for the versions that default to sorting comparable things 
in ascending order and take no arguments. For the most common case, sortedO is all you 
need. And if you want to sort in a different order, just supply a function: 

myArray.sorted(by: >) // [3,2, 1] 

You can also supply a function if your elements don’t conform to Comparable but do 
have a < operator, like tuples: 

var numberStrings = [(2, "two"), (1, "one"), (3, "three")] 
numberStrings.sort(by: <) 

numberStrings -YfC?, ’’one''), (2, "two"), (3, "three")] 


Or, you can supply a more complicated function if you want to sort by some arbitrary 
criteria: 

let animals = ["elephant", "zebra", "dog"] 
animals.sorted {Ihs, rhs in 
let I = Ihs.reversedO 
let r = rhs.reversedO 
return 1. lexicographically Precedes(r) 

} 

//["zebra", "dog", "elephant"] 

It’s this last ability — the ability to use any comparison function to sort a collection — 
that makes the Swift sort so powerful. 

Contrast this with the way sorting works in Objective-C. If you want to sort an array 
using Foundation, you’re met with a long list of different options: there are sort methods 
that take a selector, block, or function pointer as a comparison predicate, or you can pass 
in an array of sort descriptors. All of these provide a lot of flexibility and power, but at 
the cost of complexity — there isn’t an option to “just do a regular sort based on the 
default ordering.” Some variants in Foundation, like the method that takes a block as a 
comparison predicate, are essentially the same as Swift’s sorted(by:) method; others, like 
the version that takes an array of sort descriptors, make great use of Objectlve-C’s 
dynamic nature to arrive at a very flexible and powerful (if weakly typed) API that can’t 
be ported to Swift directly. 

Support for selectors and dynamic dispatch is still there in Swift, but the Swift standard 
library favors a more function-based approach instead. In this section, we’ll 
demonstrate how functions as arguments and treating functions as data can be used to 
replicate the same functionality in a fully type-safe manner. Let’s look at a complex 
example inspired by the Sort Descriptor Programming Topics guide in Apple’s 
documentation. 

We’ll start by defining a Person type. Because we want to show how Objective-C’s 
powerful runtime system works, we’ll have to make this object an NSObject subclass (in 
pure Swift, a struct might have been a better choice). We also annotate the class with 
©objcMembers to make all members visible to Objective-C: 

@objcMembers 
final class Person: NSObject { 
let first: String 
let last: String 



letyearOfBirth: Int 

init(first: String, last: String, yearOfBirth: Int) { 
self.fi rst = first 
self, last = last 

self.yearOfBirth = yearOfBirth 

} 

} 

Let’s also define an array of people with different names and birth years: 
let people = [ 

Person(first: "Emily", last: "Young", yearOfBirth: 2002), 

Person(first: "David", last: "Gray", yearOfBirth: 1991), 

Person(first: "Robert", last: "Barnes", yearOfBirth: 1985), 

Person(first: "Ava", last: "Barnes", yearOfBirth: 2000), 

Person(first: "Joanne", last: "Miller", yearOfBirth: 1994), 

Person(first: "Ava", last: "Barnes", yearOfBirth: 1998), 

] 

We want to sort this array first by last name, then by first name, and finally by birth year. 
The ordering should respect the user’s locale settings. An NSSortDescriptor object 
describes how to order objects, and we can use them to express the individual sorting 
criteria (using localizedStandardCompare as the locale-conforming comparator 
method): 

let lastDescriptor = NSSortDescriptor(key: #keyPath(Person.last), 
ascending: true, 

selector: #selector(NSString.localizedStandardCompare(_:))) 
let firstDescriptor = NSSortDescriptor(key: #keyPath(Person. first), 
ascending: true, 

selector: #selector(NSString.localizedStandardCompare(_:))) 
let yearDescriptor = NSSortDescriptor(key: #keyPath(Person.yearOfBirth), 
ascending: true) 

To sort the array, we can use the sortedArray(using:) method on NSArray. This takes a list 
of sort descriptors. To determine the order of two elements, it starts by using the first 
sort descriptor and uses that result. However, if two elements are equal according to the 
first descriptor, it uses the second descriptor, and so on: 

let descriptors = [lastDescriptor, firstDescriptor, yearDescriptor] 

(people as NSArray).sortedArray(using: descriptors) 


/* 

[Ava Barnes (1998), Ava Barnes (2000), Rabert Barnes (1985), 
David Gray (1991), Joanne Miller (199A), Emily Yaung (2002)] 
*/ 


A sort descriptor uses two runtime features of Objective-C: first, the key is an Objective-C 
key path, which is reaiiy just a string containing a chained iist of property names. Don’t 
confuse these with Swift’s native (and strongiy typed) key paths that were introduced in 
Swift 4. We’ii have more to say about the iatter beiow. 

The second Objective-C runtime feature is key-vaiue coding, which iooks up the vaiue of 
that key at runtime. The selector parameter takes a seiector (which aiso is reaiiy just a 
string describing a method name). At runtime, the seiector is used to look up a 
comparison function, and when comparing two objects, the values for the key are 
compared using that comparison function. 

This is a pretty cool use of runtime programming, especially when you realize the array 
of sort descriptors can be built at runtime, based on, say, a user clicking a column 
heading. 

How can we replicate this functionality using Swift’s sort? It’s simple to replicate parts 
of the sort — for example, if you want to sort an array using localizedStandardCompare: 


var strings = [''Hello'', "hallo", "Hallo", "hello"] 

strings.sort {$0.localizedStandardCompare($1) == .orderedAscending} 
strings//("hallo", "Hallo", "hello", "Hello"] 

If you want to sort using just a single property of an object, that’s also simple: 

people.sorted {$0.yearOfBirth < $1 .yearOfBirth } 

/* 

[Robert Barnes (1985), David Gray (1991), Joanne Miller (1994), 

Ava Barnes (1998), Ava Barnes (2000), Emily Young (2002)] 

*/ 


This approach doesn’t work so great when optional properties are combined with 
methods like localizedStandardCompare, though — it gets ugly fast. For example, 
consider sorting an array of filenames by file extension (using the fileExtension property 
from the optionals chapter): 



var files = ["one", "file.h", "file.c", "test.h"] 
files.sort {I, r in r.fileExtension.flatMap { 
l.fileExtension?.localizedStandardCompare($0) 

} == .orderedAscending} 

f\[es //["one", "file.c", "file.h", "test.h"] 

This is quite ugiy. Later on, we’ii make it easier to use optionais when sorting. However, 
for now, we haven’t even tried sorting by muitipie properties. To sort by iast name and 
then first name, we can use the standard iibrary’s lexicographicallyPrecedes method. 
This takes two sequences and performs a phonebook-styie comparison by moving 
through each pair of eiements untii it finds one that isn’t equai. So we can bulid two 
arrays of the eiements and use lexicographicallyPrecedes to compare them. This method 
aiso takes a function to perform the comparison, so we’ii put our use of 
localizedStandardCompare in the function: 

people.sorted { pO, pi in 
let left = [pO.last, pO.first] 
let right = [pi .last, pi .first] 
return left.lexicographicallyPrecedes(right) { 

$0.localizedStandardCompare($1) == .orderedAscending 

} 

} 

/* 

[Ava Barnes (2000), Ava Barnes (1998), Rabert Barnes (1985), 

David Gray (1991), Joanne Miller (199A), Emily Yaung (2002)] 

*/ 


At this point, we’ve aimost repiicated the functionaiity of the originai sort in roughiy the 
same number of iines. But there’s stiii a iot of room for improvement: the buiiding of 
arrays on every comparison is very inefficient, the comparison is hardcoded, and we 
can’t reaiiy sort by yearOfBirth using this approach. 


Functions as Data 

Rather than writing an even more compiicated function that we can use to sort, iet’s take 
a step back. So far, the sort descriptors were much ciearer, but they use runtime 
programming. The functions we wrote don’t use runtime programming, but they’re not 
so easy to write (and read). 


A sort descriptor is a way of describing the ordering of objects. Instead of storing that 
information as a ciass, we can define a function to describe the ordering of objects. The 
simpiest possibie definition takes two objects and returns true if they’re ordered 
correctiy. This is aiso exactiy the type that the standard library’s sortfby:) and sortedfby:) 
methods take as an argument. Let’s define a generic type alias to describe sort 
descriptors: 

///k sorting predicate that returns 'true' iff the first 
///value should be ordered before the second. 
typealias SortDescriptor<Value> = (Value, Value) -> Bool 

As an example, we could define a sort descriptor that compares two Person objects by 
year of birth, or a sort descriptor that sorts by last name: 

let sortByYear: SortDescriptor<Person> = {$0.yearOfBirth < $1 .yearOfBirth} 
let sortByLastName: SortDescriptor<Person> = { 

$0.last.localizedStandardCompare($1 .last) == .orderedAscending 

} 

Rather than writing the sort descriptors by hand, we can write a function that generates 
them. It’s not nice that we have to write the same property twice: in sortByLastName, we 
could have easily made a mistake and accidentally compared $0.last with $1 .first. Also, 
it’s tedious to write these sort descriptors; to sort hy first name, it’s probably easiest to 
copy and paste the sortByLastName definition and modify it. 

Instead of copying and pasting, we can dehne a function with an interface that’s a lot 
like NSSortDescriptor, hut without the runtime programming. This function takes a key 
and a comparison function, and it returns a sort descriptor (the function, not the class 
NSSortDescriptor). Here, key isn’t a string, hut is Itself a function; given an element of 
the array that’s being sorted, it returns the value of the property this sort descriptor is 
dealing with. The arelnIncreasingOrder function is then used to compare two keys. 
Finally, the return type is a function as well, even though this fact is slightly obscured by 
the type alias: 

///Builds a 'SortDescriptor' function from a sorting predicate 
/// and a 'key' function which, given a value to compare, produces 
/// the value that should be used by the sorting predicate. 
func sortDescriptor<Value, Key>( 
key: ©escaping (Value) -> Key, 

by arelnIncreasingOrder: ©escaping (Key, Key) -> Bool) 

-> SortDescriptor<Value> 


{ 


return {arelnlncreasingOrder(key($0), key($1))} 

} 


The key function describes how to driil down into a vaiue and extract the 
information that is reievant for one particular sorting step. It has a lot in 
common with Swift’s native key paths that were introduced in Swift 4. We’ll 
discuss how to rewrite this with Swift key paths below. 


This allows us to define sortByYear in a different way: 

let sortByYearAlt: SortDescriptor<Person> = 
sortDescriptor(key: {$0.yearOfBirth }, by: <) 
people.sorted(by: sortByYearAlt) 

/* 

[Robert Barnes (1985), David Gray (1991), Jaanne Miller (1994), 
Ava Barnes (1998), Ava Barnes (2000), Emily Young (2002)] 

*/ 


We can even define an overloaded variant that works for all Comparable types: 

func sortDescriptor<Value, Key>(key: ©escaping (Value) -> Key) 

-> SortDescriptor<Value> where Key: Comparable 

{ 

return { key($0) < key($1)} 

} 

let sortByYearAlt2: SortDescriptor<Person> = 
sortDescriptor(key: {$0.yearOfBirth}) 

Both sortDescriptor variants above work with functions that return a boolean value, 
because that’s the standard library’s convention for comparison predicates. Foundation 
APIs like localizedStandardCompare, on the other hand, expect a three-way 
ComparisonResult value instead (ordered ascending, descending, or equal). It’s possible 
the standard library will adopt this approach in the future . Adding support for this is 
easy as well: 


func sortDescriptor<Value, Key>( 
key: ©escaping (Value) -> Key, 
ascending: Bool = true, 




by comparator: ©escaping (Key) -> (Key) -> ComparisonResult) 
-> SortDescriptor<Value> 

{ 

return {Ihs, rhs in 

let order: ComparisonResult = ascending 
? .orderedAscending 
: .orderedDescending 

return comparator(key(lhs))(key(rhs)) == order 

} 


This allows us to write sortByFirstName in a much shorter and clearer way: 

let sortByFirstName: SortDescriptor<Person> = 
sortDescriptor(key: {$0.first}, by: String.localizedStandardCompare) 
people. sorted(by: sortByFirstName) 

/* 

[Ava Barnes (2000), Ava Barnes (1998), David Gray (1991), 

Emily Young (2002), Joanne Miller (1994), Robert Barnes (1985)] 

*/ 


This SortDescriptor is just as expressive as its NSSortDescriptor variant, but it’s type safe, 
and it doesn’t rely on runtime programming. 

Currently, we can only use a single SortDescriptor function to sort arrays. If you recall, 
we used the NSArray.sortedArray(using:) method to sort an array with more than one 
comparison operator. We could easily add a similar method to Array, or even to the 
Sequence protocol. However, we’d have to add it twice: once for the mutating variant, 
and once for the non-mutating variant of sort. 

We take a different approach so that we don’t have to write more extensions. Instead, we 
write a function that combines multiple sort descriptors into a single sort descriptor. It 
works just like the sortedArray(using:) method: first it tries the first descriptor and uses 
that comparison result. However, if the result is equal, it uses the second descriptor, and 
so on, until we run out of descriptors: 

func combine<Value> 

(sortDescriptors: [SortDescriptor<Value>]) -> SortDescriptor<Value> { 
return {lbs, rhs in 

for arelnIncreasingOrder in sortDescriptors { 
if arelnlncreasingOrder(lhs, rhs) { return true } 


if arelnlncreasingOrder(rhs, Ihs) { return false } 

} 

return false 

} 


We can now Anally replicate the initial example: 

let combined: SortDescriptor<Person> = combine! 
sortDescriptors: [sortByLastName, sortByFirstName, sortByYear] 

) 

people.sorted(by: combined) 

/* 

[Ava Barnes (1998), Ava Barnes (2000), Robert Barnes (1985), 

David Gray (1991), Joanne Miller(1994), Emily Young (2002)] 

*/ 


We ended up with the same behavior and functionality as the Foundation version, but 
our solution is safer and a lot more idiomatic in Swift. Because the Swift version doesn’t 
rely on runtime programming, the compiler can also optimize it much better. 
Additionally, we can use it with structs or non-Objective-C objects. 

One drawback of the function-based approach is that functions are opaque. We can take 
an NSSortDescriptor and print it to the console, and we get some information about the 
sort descriptor: the key path, the selector name, and the sort order. Our function-based 
approach can’t do this. If it’s important to have that information, we could wrap the 
functions in a struct or class and store additional debug information. 

This approach of using functions as data — storing them in arrays and building those 
arrays at runtime — opens up a new level of dynamic behavior, and it’s one way in which 
a statically typed compile-time-oriented language like Swift can still replicate some of 
the dynamic behavior of languages like Objectlve-C or Ruby. 

We also saw the usefulness of writing functions that combine other functions, which is 
one of the building blocks of functional programming. For example, our 
combine(sortDescriptors:) function took an array of sort descriptors and combined them 
into a single sort descriptor. This is a very powerful technique with many different 
applications. 

Alternatively, we could even have written a custom operator to combine two sort 
functions: 


infix operator <||> : LogicalDisjunctionPrecedence 

func <||><A>(lhs: ©escaping (A,A) -> Bool, rhs: ©escaping (A,A) -> Bool) 

-> (A,A) -> Bool 

{ 

return {x,y in 
if lhs(x, y) { return true } 
if lhs(y, x) { return false } 

// Otherwise they're the same, so we check for the second condition 
if rhs(x, y) { return true } 
return false 

} 

} 

Most of the time, writing a custom operator is a bad idea. Custom operators are often 
harder to read than functions are, because the name isn’t expiicit. However, they can be 
very powerfui when used sparingly. The operator above ailows us to rewrite our 
combined sort exampie, iike so: 

let combinedAlt = sortByLastName <||> sortByFirstName <||> sortByYear 
people.sorted(by: combinedAlt) 

/* 

[Ava Barnes (1998), Ava Barnes (2000), Robert Barnes (1985), 

David Gray (1991), Joanne Miller(1994), Emiiy Young (2002)] 

*/ 


This reads very cleariy and perhaps aiso expresses the code’s intent more succinctiy 
than the aiternative, but only after you (and every other reader of the code) have 
ingrained the meaning of the operator. We prefer the combine(sortDescriptors:) function 
over the custom operator. It’s clearer at the call site and ultimately makes the code more 
readable. Unless you’re writing highly domain-specific code, a custom operator is 
probably overkill. 

The Foundation version still has one functional advantage over our version: it can deal 
with optionals without having to write any more code. For example, if we’d make the last 
property on Person an optional string, we wouldn’t have to change anything in the 
sorting code that uses NSSortDescriptor. 

The function-based version requires some extra code. You can probably guess what 
comes next: once again, we write a function that takes a function and returns a function. 
We can take a regular comparison function such as localizedStandardCompare, which 
works on two strings, and turn it into a function that takes two optional strings. If both 


values are nil, they’re equal. If the left-hand side Is nil, but the right-hand side isn’t, 
they’re ascending, and the other way around. Finally, if they’re both non-nil, we can use 
the compare function to compare them: 

func lift<A>L compare: ©escaping (A) -> (A) -> ComparisonResult) -> (A?) -> (A?) 

-> ComparisonResult 

{ 

return {Ihs in {rhs in 
switch (Ihs, rhs) { 

case (nil, nil): return .orderedSame 
case (nil, _): return .orderedAscending 
case (_, nil): return .orderedDescending 
case let (I?, r?): return compare(l)(r) 

} 

}} 

} 

This allows us to “lift” a regular comparison function into the domain of optionals, and 
it can be used together with our sortDescriptor function. If you recall the files array from 
before, sorting it by fileExtension got really ugly because we had to deal with optionals. 
However, with our new lift function, it’s very clean again: 

let compare = lift(String.localizedStandardCompare) 
let result = files.sorted(by: sortDescriptor(key: {$0.fileExtension}, 
by: compare)) 

result//fone" "file.c", "file.h", "test.h"] 


We can write a similar version of lift for functions that return a Bool. As we saw 
in the optionals chapter, the standard library no longer provides comparison 
operators like > for optionals. They were removed because using them can lead 
to surprising results if you’re not careful. A boolean variant of lift allows you to 
easily take an existing operator and make it work for optionals when you need 
the functionality. 


This approach has also given us a clean separation between the sorting method and the 
comparison method. The algorithm that Swift’s sort uses is a hybrid of multiple sorting 
algorithms — as of this writing, it’s an introsort (which is itself a hybrid of a quicksort 
and a heapsort), but it switches to an insertion sort for small collections to avoid the 
upfront startup cost of the more complex sort algorithms. 






Introsort isn’t a " stable” sort. That is, it doesn’t necessarily maintain relative ordering of 
values that are otherwise equal according to the comparison function. But if you 
implemented a stable sort, the separation of the sort method from the comparison 
would allow you to swap it in easily: 

people.stablySorted(by: combine( 
sortDescriptors: [sortByLastName, sortByFirstName, sortByYear] 

)) 


Local Functions and Variable Capture 

If we wanted to implement such a stable sort, one choice might he a merge sort . The 
merge sort algorithm is made up of two parts: a division into sublists of one element, 
followed by a merge of those lists. Often, it’s nice to dehne merge as a separate function. 
But this leads to a problem — merge requires some temporary scratch storage: 

extension Array where Element: Comparable { 
private mutating func merge(lo: Int, mi: Int, hi: Int) { 
var tmp: [Element] = [] 
var i = lo, j = mi 
while i 1= mi && j != hi { 
if self[j] < self [i] { 
tmp.append(self[j]) 
j+=1 
} else { 

tmp.append(self[i]) 
i += 1 

} 

} 

tmp.append(contentsOf: self[i..<mi]) 
tmp.append(contentsOf: self[j..<hi]) 
replaceSubrange(lo..<hi, with: tmp) 

} 

mutating func mergeSortlnPlacelnefficientQ { 
let n = count 
var size = 1 
while size < n { 

for lo in stride(from: 0, to: n-size, by: size*2) { 
merge(lo: lo, mi: (lo+size), hi: Swift.min(lo+size*2,n)) 




} 

size *= 2 

} 

} 

} 


Note: because Array has a method named min() defined, we need to write 
Swift. min. This tells the compiler to explicitly use the standard library’s free 
function named min (instead of the method on Array). 


Of course, we could allocate this storage externally and pass it in as a parameter, but this 
is a little ugly. It’s also complicated by the fact that arrays are value types — passing in 
an array we created outside wouldn’t help. There’s an optimization that replaces inout 
parameters with references, but the documentation tells us specifically not to rely on 
that. 

As another solution, we can define merge as an inner function and have it capture the 
storage defined in the outer function’s scope: 

extension Array where Element: Comparable { 
mutatingfunc mergeSortlnPlaceO { 

// Define the temporary storage far use by all merges 
var tmp: [Element] = [] 

// and make sure it's big enough 
tmp.reserveCapacity(count) 

func merge(lo: Int, mi: int, hi: int) { 

// Wipe the storage clean while retaining its capacity 
tmp.removeAll(keepingCapacity: true) 

// The same cade as befare 
var i = lo, j = mi 
while i != mi && j != hi { 
if self [j] < self[i] { 
tmp.append(self[j]) 
j+=1 
} else { 

tmp.append(self[i]) 
i += 1 


} 



} 

tmp.append(contentsOf: self[i..<mi]) 
tmp.append(contentsOf: self[j..<hi]) 
replaceSubrange(lo..<hi, with: tmp) 

} 

let n = count 
var size = 1 
while size < n { 

for lo in stride(from: 0, to: n-size, by: size*2) { 
merge(lo: lo, mi: (lo+size), hi: Swift.min(lo+size*2,n)) 

} 

size *= 2 

} 

} 

} 

Since closures (including inner functions) capture variables by reference, every call to 
merge within a single call to mergeSortInPlace will share this storage. But it’s still a local 
variable — separate concurrent calls to mergeSortInPlace will use separate instances. 
Using this technique can give a significant speed boost to the sort without needing major 
changes to the original version. 


Functions as Delegates 

Delegates. They’re everywhere. Drummed into the heads of Ob|ective-C (and Java) 
programmers is this message: use protocols (interfaces) for callbacks. You define a 
protocol, your owner implements that protocol, and it registers itself as your delegate so 
that it gets callbacks. 

If a delegate protocol contains only a single method, you can mechanically replace the 
property storing the delegate object with one that stores the callback function directly. 
However, there are a number of tradeoffs to keep in mind. 


Delegates, Foundation-Style 


Let’s start off by creating a protocol in the same way that Cocoa defines its countless 
delegate protocols. Most programmers who come from Objective-C have written code 
like this many times over: 

protocol AlertViewDelegate: AnyObject { 
func buttonTappedfatIndex: Int) 

} 

It’s defined as a class-only protocol because we want our AlertView class to hold a weak 
reference to the delegate. This way, we don’t have to worry about reference cycles. An 
AlertView will never strongly retain its delegate, so even if the delegate (directly or 
indirectly) has a strong reference to the alert view, all is well. If the delegate is 
deinitialized, the delegate property will automatically become nil: 

class AlertView { 
var buttons: [String] 
weak var delegate: AlertViewDelegate? 

init(buttons: [String] = ["OK", "Cancel"]) { 
self.buttons = buttons 

} 

func fireO { 

delegate?.buttonTapped(atlndex: 1) 

} 

} 

This pattern works really well when we’re dealing with classes. For example, suppose we 
have a ViewController class that initializes the alert view and sets itself as the delegate. 
Because the delegate is marked as weak, we don’t need to worry about reference cycles: 

class ViewController: AlertViewDelegate { 
let alert: AlertView 

initO { 

alert = AlertViewfbuttons: ["OK", "Cancel"]) 
alert.delegate = self 

} 


func buttonTapped(atlndex index: Int) { 
printC'Button tapped: \(index)") 

} 

} 

It’s common practice to always mark delegate properties as weak. This convention 
makes reasoning about the memory management very easy. Classes that implement the 
delegate protocol don’t have to worry about creating a reference cycle. 


Delegates That Work with Structs 

Sometimes we might want to have a delegate protocol that’s implemented by a struct. 
With the current definition of AlertViewDelegate, this is impossible, because it’s a 
class-only protocol. 

We can loosen the definition of AlertViewDelegate by not making it a class-only protocol. 
Also, we’ll mark the buttonTappedfatIndex:) method as mutating. This way, a struct can 
mutate itself when the method gets called: 

protocol AlertViewDelegate { 
mutating func buttonTappedfatIndex: Int) 

} 

We also have to change our AlertView because the delegate property can no longer be 
weak: 

class AlertView { 
var buttons: [String] 
var delegate: AlertViewDelegate? 

initfbuttons: [String] = ["OK", "Cancel"]) { 
self.buttons = buttons 

} 

func fireO { 

delegate?.buttonTapped(atlndex: 1) 

} 

} 


If we assign an object to the delegate property, the object will be strongly referenced. 
Especially when working with delegates, the strong reference means there’s a very high 
chance that we’ll introduce a reference cycle at some point. However, we can use structs 
now. For example, we could create a struct that logs all button taps: 

struct TapLogger: AlertViewDelegate { 
vartaps: [Int] = [] 

mutatingfunc buttonTapped(atlndex index: Int) { 
taps.append(index) 

} 

} 

At first, it might seem like everything works well. We can create an alert view and a 
logger and connect the two. Alas, if we look at logger.taps after an event is fired, the 
array is still empty: 

let alert = AlertViewQ 
var logger = TapLoggerQ 
alert.delegate = logger 
alert.fi re() 
logger.taps//fj 

When we assigned to alert.delegate. Swift made a copy of the struct. So the taps aren’t 
recorded in logger, but rather in alert.delegate. Even worse, when we assign the value, 
we lose the value’s type. To get the information back out, we need to use a conditional 
type cast: 

if let theLogger = alert.delegate as? TapLogger { 
print(theLogger.taps) 

} 

.7 1 Ij 


Clearly this approach doesn’t work well. When using classes, it’s easy to create reference 
cycles, and when using structs, the original value doesn’t get mutated. In short: delegate 
protocols don’t make much sense when using structs. 


Functions Instead of Delegates 


If the delegate protocol only has a single method dehned, we can simply replace the 
delegate property with a property that stores the callback function directly. In our case, 
this could he an optional buttonTapped property, which is nil by default: 

class AlertView { 
var buttons: [String] 

var buttonTapped: ((_ buttonindex: Int) -> ())? 

init(buttons: [String] = ["OK", "Cancel"]) { 
self.buttons = buttons 

} 

func fireO { 
buttonTapped?(1) 

} 

} 

The (_ buttonindex: Int) -> () notation for the function type is a little weird because the 
internal name, buttonindex, isn’t relevant anywhere else in the code. We mentioned 
above that function types unfortunately can’t have parameter labels; they can however 
have an explicit blank parameter label combined with an internal argument name. This 
is the offlcially sanctioned workaround to give parameters in function types labels for 
documentation purposes until Swift supports a better way. 

Just like before, we can create a logger struct and then create an alert view instance and 
a logger variable: 

struct TapLogger { 
var taps: [Int] = [] 

mutating func logTap(index: Int) { 
taps.append(index) 

} 

} 

let alert = AlertViewO 
var logger = TapLoggerQ 



However, we can’t simply assign the logTap method to the buttonTapped property. The 
Swift compiler tells us that “partial application of a ‘mutating’ method is not allowed”: 

alert.buttonTapped = logger.logTapError 

In the code above, it’s not clear what should happen in the assignment. Does the logger 
get copied? Or should buttonTapped mutate the original variable (i.e. logger gets 
captured)? 

To make this work, we have to wrap the right-hand side of the assignment in a closure. 
This has the benefit of making it very clear that we’re now capturing the original logger 
variable (not the value) and that we’re mutating it: 

alert.buttonTapped = {logger.logTap(index: $0)} 

As an additional benefit, the naming is now decoupled: the callback property is called 
buttonTapped, but the function that implements it is called logTap. Rather than a 
method, we could also specify an anonymous function: 

alert.buttonTapped = { printC'Button \($0) was tapped") } 

When combining callbacks with classes, there are some caveats. Let’s go back to our view 
controller example. In its initializer, instead of assigning itself as the alert view’s 
delegate, the view controller can now assign its buttonTapped method to the alert view’s 
callback handler: 

class ViewController { 
let alert: AlertView 

initO { 

alert = AlertView(buttons: ["OK", "Cancel"]) 
alert.buttonTapped = self.buttonTapped(atlndex:) 

} 

func buttonTapped(atlndex index: Int) { 
printC'Button tapped: \(index)'') 

} 

} 

The alert.buttonTapped = self.buttonTapped(atlndex:) line looks like an innocent 
assignment, but beware: we’ve just created a reference cycle! Every reference to an 


instance method of an object (like self.buttonTapped in the example) implicitly captures 
the object. To see why this has to be the case, consider the perspective of the alert view: 
when the alert view calls the callback function that’s stored in its buttonTapped property, 
the function must somehow “know” which object’s Instance method it needs to call — 
it’s not enough to just store a reference to ViewController.buttonTappedjatIndex:) without 
knowing the instance. 


We could’ve shortened self.buttonTappedjatlndex:) to self.buttonTapped or just 
buttonTapped; all three refer to the same function. Parameter labels can be 
omitted as long as doing so doesn’t create ambiguities. 


It’s very easy to accidentally create reference cycles this way. To avoid a strong reference, 
it’s often necessary to wrap the method call in another closure that captures the object 
weakly: 

alert.buttonTapped = {[weak self] index in 
self?.buttonTapped(atlndex: index) 

} 

This way, the alert view doesn’t have a strong reference to the view controller. If we can 
guarantee that the alert view’s lifetime is tied to the view controller, another option is to 
use [unowned self] instead of weak. With weak, should the alert view outlive the view 
controller, self will be nil inside the closure when the function gets called. 


If you check out the type of the expression ViewController.buttonTapped, 
you’ll notice that it’s (ViewController) -> (Int) -> (). What’s going on there? 

Under the hood, instance methods are modeled as functions that, 
given an instance, return another function that then operates on the 
instance. someVC.buttonTapped is really just another way of writing 
ViewController.buttonTapped(someVC) — both expressions return a function of 
type (Int) -> (), and this function is a closure that has strongly captured the 
someVC instance. 


As we’ve seen, there are definite tradeoffs between protocols and callback functions. A 
protocol adds some verbosity, but a class-only protocol with a weak delegate removes 
the need to worry about introducing reference cycles. 




Replacing the delegate with a function adds a lot of flexibility and allows you to use 
structs and anonymous functions. However, when dealing with classes, you need to be 
careful not to introduce a reference cycle. 


Also, when you need multiple callback functions that are closely related (for example, 
providing the data for a table view). It can be helpful to keep them grouped together in a 
protocol rather than having individual callbacks. When using a protocol, a single type 
has to implement all the methods. 

To unreglster a delegate or a function callback, we can simply set it to nil. What about 
when our type stores an array of delegates or callbacks? With class-based delegates, we 
can simply remove an object from the delegate list. With callback functions, this isn’t so 
simple; we’d need to add extra infrastructure for unregistering, because functions can’t 
be compared. 


inout Parameters and Mutating Methods 

The “&” that we use at the front of an inout argument In Swift might give you the 
impression — especially if you have a C or C++ background — that inout parameters are 
essentially pass-by-reference. But they aren’t, inout is pass-by-value-and-copy-back, not 
pass-by-reference. To quote the official Swift Programming Language book: 


An inout parameter has a value that Is passed in to the function, is modified by 
the function, and is passed back out of the function to replace the original 
value. 


In the chapter on structs and classes, we wrote about inout parameters, and we looked at 
the similarities between mutating methods and methods that take an inout parameter. 

In order to understand what kind of expressions can be passed as an inout parameter, we 
need to make the distinction between lvalues and rvalues. An lvalue describes a 
memory location, lvalue is short for “left value,” because lvalues are expressions that 
can appear on the left side of an assignment. For example, arrayjO] is an lvalue, as it 
describes the memory location of the first element in the array. An rvalue describes a 
value. 2 + 2 is an rvalue, as it describes the value 4. You can’t put 2 + 2 or 4 on the left 
side of an assignment statement. 



For inout parameters, you can only pass lvalues, because it doesn’t make sense to mutate 
an rvalue. When you’re working with inout parameters in reguiar functions and 
methods, you need to he expiicit about passing them in: every ivalue needs to be 
prefixed with an &. For example, when we call the increment function (which takes an 
inout Int), we can pass in a variabie by prehxing it with an ampersand: 

func increment(value: inout Int) { 
value += 1 

} 

var i = 0 

increment(value: &i) 

If we define a variabie using let, we can’t use it as an ivaiue. This makes sense, because 
we’re not aiiowed to mutate let variables; we can only use “mutable” lvalues: 

lety: Int = 0 

increment(value: &y)//Error 

In addition to variables, a few more things are also lvalues. For example, we can also 
pass in an array subscript (if the array is defined using var): 

var array = [0,1,2] 
increment(value: &array[0]) 
array//fl, 1,2] 

In fact, this works with every subscript (including your own custom subscripts), as long 
as they both have a get and a set defined. Likewise, we can use properties as lvalues, hut 
again, only if they have both get and set defined: 

struct Point { 
var x: Int 
vary: Int 

} 

var point = Point(x: 0, y: 0) 
increment(value: Spoint.x) 
point // Point(x: 1, y: 0) 

If a property is read-only (that is, only get Is available), we can’t use it as an inout 
parameter: 


extension Point { 


var squaredDistance: Int { 
return x*x + y*y 

} 

} 

increment(value: &point.squaredDistance) //Error 

Operators can also take an inout value, but for the sake of simplicity, they don’t require 
the ampersand when called; we just specify the lvalue. For example, let’s add back the 
postfix increment operator, which was removed in Swift 3 : 

postfixfunc ++(x: inout Int) { 

X += 1 

} 

point.X++ 

point // Point(x: 2, y: 0) 

A mutating operator can even be combined with optional chaining. Here, we chain the 
increment operation to a dictionary subscript access: 

var dictionary = ["one”: 1] 
dictionary["one"]?++ 
dictionary["one"] //Opt/ono/(2) 

Note that the ++ operator won’t get executed if the key lookup returns nil. 

The compiler may optimize an inout variable to pass-by-reference, rather than copying 
in and out. However, it’s explicitly stated in the documentation that we shouldn’t rely on 
this behavior. 


Nested Functions and inout 

You can use an inout parameter inside nested functions, but Swift will make sure your 
usage is safe. For example, you can define a nested function (either using func or using a 
closure expression) and safely mutate an inout parameter: 

func incrementTenTimes(value: inout Int) { 
func inc() { 
value -l-= 1 

} 



for _ in 0..<10 { 
incO 

} 

} 

var X = 0 

incrementTenTimes(value: &x) 
X//70 


However, you’re not allowed to let that inout parameter escape (we’ll talk more about 
escaping functions at the end of this chapter): 

func escapelncrement(value: inout Int) -> () -> () { 
func inc() { 
value += 1 

} 

// error: nested function cannot capture inout parameter 
//and escape 

return inc 

} 

This makes sense, given that the inout value is copied back just before the function 
returns. If we could somehow modify it later, what should happen? Should the value get 
copied back at some point? What if the source no longer exists? Having the compiler 
verify this is critical for safety. 


When & Doesn’t Mean inout 

Speaking of unsafe functions, you should be aware of the other meaning of &: 
converting a function argument to an unsafe pointer. 

If a function takes an UnsafeMutablePointer as a parameter, then you can pass a var into 
it using &, similar to an inout argument. But here you really are passing by reference — 
by pointer in fact. 

Here’s increment, written to take an unsafe mutable pointer instead of an inout: 

func incref(pointer: UnsafeMutablePointer<lnt>) -> () -> Int { 

//Store a copy of the pointer in a closure 


return { 

pointer.pointee+= 1 
return pointer.pointee 

} 

} 

As we’ll discuss in later chapters. Swift arrays implicitly decay to pointers to make C 
interoperability nice and painless. Now, suppose you pass in an array that goes out of 
scope before you call the resulting function: 

let fun: () -> Int 
do { 

var array = [0] 

fun = incref(pointer: &array) 

} 

fun() 

This opens up a whole exciting world of undefined behavior. In testing, the above code 
printed different values on each run: sometimes 0, sometimes 1, sometimes 
140362397107840 — and sometimes it produced a runtime crash. 

The moral here is: know what you’re passing in to. When appending an &, you could be 
invoking nice safe Swift inout semantics, or you could be casting your poor variable into 
the brutal world of unsafe pointers. When dealing with unsafe pointers, be very careful 
about the lifetime of variables. We’ll go into more detail on this in the chapter on 
interoperability. 


Properties 

There are two special kinds of methods that differ from regular methods: computed 
properties and subscripts. A computed property looks like a regular property, but it 
doesn’t use any memory to store its value. Instead, the value is computed on the fly 
every time the property is accessed. A computed property is really just a method with 
unusual defining and calling conventions. 

Let’s look at the various ways to define properties. We’ll start with a struct that 
represents a GPS track. It stores all the recorded points in an array called record: 


import CoreLocation 


struct GPSTrack { 
var record: [(CLLocation, Date)] = [] 

} 

If we want to make the record property available as read-only to the outside, but 
read-write internally, we can use the private(set) or fileprivate(set) modifiers: 

struct GPSTrack { 

private(set) var record: [(CLLocation, Date)] = [] 

} 

To access all the timestamps in a GPS track, we create a computed property: 
extension GPSTrack { 

///Returns all the timestamps for the GPS track. 

/// - Complexity: 0(*n*), where *n* is the number of points recorded. 
var timestamps: [Date] { 
return record.map {$0.1 } 

} 

} 

Because we didn’t specify a setter, the timestamps property is read-only. The result isn’t 
cached; each time you access the property, it computes the result. The Swift API Design 
Guidelines recommend you document the complexity of every computed property that 
isn’t 0(1), because callers might assume that accessing a property takes constant time. 


Change Observers 

As we saw in the chapter on structs and classes, we can also implement the wiUSet and 
didSet handlers for properties and variables to get called every time a property is set 
(even if the value doesn’t change). These get called immediately before and after the 
new value is stored, respectively. One useful case is when working with Interface 
Builder: we can implement didSet to know when an IBOutlet gets connected, and then 
perform additional configuration in the handler. For example, if we want to set a label’s 
text color once it’s available, we can do the following: 

class SettingsControUer: UlViewController { 

©IBOutlet weak var label: UlLabel? { 
didSet { 


label?.textColor = .black 


} 

} 

} 

The observers have to be dehned at the declaration site of a property — you can’t add 
one retroactively in an extension. They are therefore a tool for the designer of the type, 
and not the user. The wiUSet and didSet handlers are essentially shorthand for defining 
a pair of properties: one private stored property that provides the storage, and a public 
computed property whose setter performs additional work before and/or after storing 
the value in the stored property. This is fundamentally different from the key-value 
o bserving mechanism in Foundation, which is often used by consumers of an object to 
observe internal changes, whether or not the class’s designer intended this. 

You can override a property in a subclass to add an observer, however. Here’s an 
example: 

class Robot { 
enum State { 

case stopped, movingForward, turningRight, turningLeft 

} 

var state = State.stopped 

} 

class ObservableRobot: Robot { 
override var state: State { 
willSet { 

printC'Transitioning from \(state) to \(newValue)") 

} 

} 

} 

var robot = ObservableRobotO 

robot.state = .movingForward //Transitioning from stopped to movingForward 

This is still consistent with the nature of change observers as an internal characteristic 
of a type. If it weren’t allowed, a subclass could achieve the same effect by overriding a 
stored property with a computed setter that performs additional work. 

The difference in usage is reflected in the implementation of these features. KVO uses 
the Objective-C runtime to dynamically add an observer to a class’s setter, which would 




be impossible to implement in current Swift, especially for value types. Swift’s property 
observers are a purely compile-time feature. 


Lazy Stored Properties 

Initializing a value lazily is such a common pattern that Swift has a special keyword, 
lazy, for defining lazy properties. Note that a lazy property must always he declared as 
var because its Initial value might not be set until after initialization completes. Swift 
has a strict rule that let constants must have a value before an instance’s initialization 
completes. The lazy modifier is a very specific form of memoization. 

For example, if we have a view controller that displays a G PST rack, we might want to 
have a preview image of the track. By making the property for that lazy, we can defer the 
expensive generation of the image until the property is accessed for the first time: 

class GPSTrackViewController: UlViewController { 
var track: GPSTrack = GPSTrackO 

lazy var preview: Ullmage = { 
for point in track.record { 

//Do some expensive computation 

} 

return Ullmage(/*... */) 

}() 


Notice how we defined the lazy property: it’s a closure expression that returns the value 
we want to store — in our case, an image. When the property is first accessed, the closure 
is executed (note the parentheses at the end), and its return value is stored in the 
property. This is a common pattern for lazy properties that require more than a 
one-liner to be initialized. 

Because a lazy variable needs storage, we’re required to define the lazy property in the 
definition of GPSTrackViewController. Unlike computed properties, stored properties 
and stored lazy properties can’t be defined in an extension. 

If the track property changes, the preview won’t automatically get invalidated. Let’s look 
at an even simpler example to see what’s going on. We have a Point struct, and we store 
distanceFromOrigin as a lazy computed property: 



struct Point { 
var x: Double 
vary: Double 

private(set) lazy var distanceFromOrigin: Double 
= (x*x + y*y).squareRoot() 

init(x: Double, y: Double) { 
self.x = X 
self.y = y 

} 

} 

When we create a point, we can access the distanceFromOrigin property, and it’ll 
compute the value and store it for reuse. However, if we then change the x value, this 
won’t be reflected in distanceFromOrigin: 

var point = Point(x: 3, y: 4) 
point.distanceFromOrigin //5.0 
point.X +=10 

point.distanceFromOrigin //5.0 

It’s important to be aware of this. One way around it would be to recompute 
distanceFromOrigin in the didSet property observers of x and y, but then 
distanceFromOrigin isn’t really lazy anymore: it’ll get computed each time x or y changes. 
Of course, in this example, the solution is easy: we should have made 
distanceFromOrigin a regular (non-lazy) computed property from the beginning. 

Accessing a lazy property is a mutating operation because the property’s initial value Is 
set on the first access. When a struct contains a lazy property, any owner of the struct 
that accesses the lazy property must therefore declare the struct as a variable too, 
because accessing the property means potentially mutating its container. So this isn’t 
allowed: 

let immutablePoint = Point(x: 3, y: 4) 
immutable Point.distanceFromOrigin 
//Error: Cannot use mutating getter on immutable value 

Forcing all users of the Point type who want to access the lazy property to use var is a 
huge inconvenience, which often makes lazy properties a bad fit for structs. 


Also be aware that the lazy keyword doesn’t perform any thread synchronization, if 
multiple threads access a lazy property at the same time before the value has been 
computed, it’s possible the computation could be performed more than once, including 
any side effects the computation may have. 

Early in Swift’s open-source era, the Swift team proposed a general mechanism for 
annotating properties with “ behaviors .” If implemented, current primitive language 
features like property observers and lazy properties could be moved from the compiler 
into the standard library, making the compiler less complex and allowing all developers 
to add their own behaviors. The proposal was widely welcomed by the community but 
ultimately deferred due to time constraints. Something like property behaviors could 
still come in a future version of Swift. 


Subscripts 

We’ve already seen subscripts in the standard library. For example, we can perform a 
dictionary lookup like so: dictionary[key]. These subscripts are very much a hybrid of 
functions and computed properties, with their own special syntax. Like functions, they 
take arguments. Like computed properties, they can be either read-only (using get) or 
read-write (using get set). Just like normal functions, we can overload them by 
providing multiple variants with different types — something that isn’t possible with 
properties. For example, arrays have two subscripts by default — one to access a single 
element, and one to get at a slice (to be precise, these are declared in the Collection 
protocol): 

let fibs = [0,1,1,2,3, 5] 
let first = fibs[0] // 0 
fibs[1..<3]///'7, 7J 


Custom Subscripts 

We can add subscripting support to our own types, and we can also extend existing types 
with new subscript overloads. As an example, let’s define a Collection subscript that 
takes a list of Indices and returns an array of all elements at those indices: 

extension Collection { 

subscript(indices indexList: Index...) -> [Element] { 
var result: [Element] = [] 



for index in indexList { 
result.append(self [index]) 

} 

return result 

} 


Note how we used an explicit parameter label to disambiguate our subscript from those 
in the standard library. The three dots indicate that indexList is a variadicparameter. 
The caller can pass zero or more comma-separated values of the specified type (here, the 
collection’s Index type). Inside the function, the parameters are made available as an 
array. 

We can use the new subscript like this: 

Array("abcdefghijklmnopqrstuvwxyz'')[indices: 7,4,11,11,14] 

//["h", "e" "I", "I", "o"] 


Advanced Subscripts 

Subscripts aren’t limited to a single parameter. We’ve already seen an example of a 
subscript that takes more than one parameter: the dictionary subscript that takes a key 
and a default value. Check out its implementation in the Swift source code if you’re 
interested. 

New in Swift 4, subscripts can now also be generic in their parameters or their return 
type. Consider a heterogeneous dictionary of type [String: Any]: 

var japan: [String: Any] = [ 

"name": "Japan", 

"capital": "Tokyo", 

"population": 126_740_000, 

"coordinates": [ 

"latitude": 35.0, 

"longitude": 139.0 

] 

] 



If you want to mutate a nested value in this dictionary, e.g. the coordinate’s latitude, 
you’ll And it isn’t so easy: 

// Error: Type 'Any' has no subscript members 
japan["coordinate'']?["latitude"] = 36.0 

OK, that’s understandable. The expression japan[''coordinate''] has the type Any?, so 
you’d probably try to cast it to a dictionary before applying the nested subscript: 

// Error: Cannot assign to immutable expression 
(japan["coordinates"] as? [String: Doubie])?["coordinate''] = 36.0 

Alas, not only is this becoming ugly fast, but it doesn’t work either. The problem is that 
you can’t mutate a variable through a typecast — the expression 
japan[''coordinates"] as? [String: Double] is no longer an lvalue. You’d have to store the 
nested dictionary in a local variable first, then mutate that variable, and then assign the 
local variable back to the top-level key. 

We can do better by extending Dictionary with a generic subscript that takes the desired 
target type as a second parameter and attempts the cast inside the subscript 
implementation: 

extension Dictionary { 

subscript<Result>(key: Key, as type: Result.Type) -> Result? { 
get{ 

return self[key] as? Result 

} 

set { 

guard let value = newValue as? Value else { 
return 

} 

self[key] = value 

} 

} 

} 

Since we no longer have to downcast the value returned by the subscript, the mutation 
operation goes through to the top-level dictionary variable: 

japan["coordinates", as: [String: Double]. self]?["latitude"] = 36.0 
japan["coordinates"] /yOpt/ono/fr'/ot/tude"; 36.0, "longitude": 139.0]) 


Generic subscripts close an important hole in the type system. That said, you’ll notice 
the final syntax in this example is still quite ugly. Swift is generally not well suited for 
working on heterogeneous collections like this dictionary. In most cases, you’ll be better 
off defining your own custom types for your data (e.g. here, a Country struct) and 
conforming those types to Codable for converting value to and from data transfer 
formats. 


Key Paths 

Swift 4 added the concept of key paths to the language. A key path is an uninvoked 
reference to a property, analogous to an unapplied method reference. Key paths close a 
fairly hig hole in Swift’s type system; previously, it wasn’t possible to refer to a type’s 
property, such as String.count, in the same way you could refer to a method, such as 
String.uppercased. Despite sharing the same name. Swift’s key paths are quite different 
from the key paths used in Objective-C and Foundation. We’ll have more to say about 
this later. 

Key path expressions start with a backslash, e.g. \String.count. The backslash is 
necessary to distinguish a key path from a type property of the same name that may 
exist (suppose that String also had a static count property — then String.count would 
return the value of that property). Type inference works in key path expressions too: you 
can omit the type name if the compiler can infer it from the context, leaving \.count. 


Given that key paths and function type references are so closely related, it’s 
unfortunate that Swift has different syntaxes for the two. Even so, the Swift 
team has expressed interest in adopting the backslash syntax for function type 
references in a future release. 


As the name suggests, a key path describes a path through a value hierarchy, starting at 
the root value. For example, given the following Person and Address types, 

\Person.add ress.street is a key path that resolves a person’s street address: 

struct Address { 
var street: String 
var city: String 
var zipCode: Int 


} 



struct Person { 
let name: String 
var address: Address 

} 

let streetKeyPath = \Person.address.street // WritableKeyPath<Person, String> 
let nameKeyPath = \Person.name//KeyPath<Person, Stringy 

Key paths can be composed of any combination of stored and computed properties, 
aiong with optionai chaining operators. The compiier automaticaiiy generates a new 
[keyPath:] subscript for ali types. You use this subscript to “invoke” the key path, i.e. to 
access the property described by it on a given instance. So ''Hello''[keyPath: \.count] is 
equivaient to ''Hello''.count. Or, for our current example: 

let simpsonResidence = Address(street: "1094 Evergreen Terrace", 
city: "Springfield", zipCode: 97475) 

var lisa = Person(name: "Lisa Simpson", address: simpsonResidence) 
lisa[keyPath: nameKeyPath] //L/so Simpson 

If you look at the types of our two key path variables above, you’ll notice that the type of 
nameKeyPath is KeyPathtPerson, String> (i.e. a strongly typed key path that can be 
applied to a Person and yields a String), whereas streetKeyPath’s type is WritableKeyPath. 
Because all properties that form this latter key path are mutable, the key path itself 
allows mutation of the underlying value: 

lisa[keyPath: StreetKeyPath] = "742 Evergreen Terrace" 

Doing the same with nameKeyPath would produce an error because the underlying 
property isn’t mutable. 


Key Paths Can Be Modeled with Functions 

A key path that maps from a base type Root to a property of type Value is very similar to a 
function of type (Root) -> Value — or, for writable key paths, a pair of functions for both 
getting and setting a value. The major benefit key paths have over such functions (aside 
from the syntax) is that they are values. You can test key paths for equality and use them 
as dictionary keys (they conform to Hashable), and you can be sure that a key path is 
stateless, unlike functions, which might capture mutable state. None of these things are 
possible with normal functions. 


Key paths are also composable by appending one key path to another. Notice that the 
types must match: if you start with a key path from A to B, the key path you append 
must have a root type of B, and the resulting key path will then map from A to the 
appended key path’s value type, say C: 

// KeyPath<Person, Stnng> + KeyPath<String, lnt> = KeyPath<Person, lnt> 
let nameCountKeyPath = nameKeyPath.appending(path: \.count) 

// Swift.KeyPath<Person, Swift. Int> 

Let’s rewrite our sort descriptors from earlier in this chapter to use key paths instead of 
functions. We previously defined sortDescriptor as taking a function, (Key) -> Value: 

typealias SortDescriptor<Value> = (Value, Value) -> Bool 
func sortDescriptoKValue, Key>(key: ©escaping (Value) -> Key) 

-> SortDescriptor<Value> where Key: Comparable { 
return { key($0) < key($1)} 

} 

// Usage 

let streetSD: SortDescriptor<Person> = sortDescriptor {$0.address.street} 

We can add a variant for constructing a sort descriptor from a key path. We use the 
subscript for key paths to access the value: 

func sortDescriptortValue, Key>(key: KeyPathtValue, Key>) 

-> SortDescriptor<Value> where Key: Comparable { 
return {$0[keyPath: key] < $1 [keyPath: key]} 

} 

// Usage 

let streetSDKeyPath: SortDescriptor<Person> = 
sortDescriptor(key: \.address.street) 

While it’s useful to have a sortDescriptor constructor that takes a key path, it doesn’t give 
us the same flexibility as functions do. The key path relies on the Value being 
Comparable. Using just key paths, we can’t easily sort by a different predicate (for 
example, performing a localized case-insensitive comparison). 


Writable Key Paths 


A writable key path is special; you can use it to read or write a value. Hence, it’s 
equivalent to a pair of functions: one for getting {(Root) -> Value), and another for setting 
((inout Root, Value) -> Void) the property. Writable key paths are a much bigger deal than 
the read-only key paths. First of all, they capture a lot of code in a neat syntax. Compare 
streetKeyPath with the equivalent getter and setter pair: 

let StreetKeyPath = \Person.address.street 

let getStreet: (Person) -> String = { person in 
return person.address.street 

} 

let setStreet: (inout Person, String) ->() = { person, newValue in 
person.address.street = newValue 

} 

// Usage 

lisa[keyPath: streetKeyPath] 742 Evergreen Terrace 
getStreet(lisa) // 742 Evergreen Terrace 

Writable key paths are especially useful for data binding, where you want to bind two 
properties to each other: when property one changes, property two should automatically 
get updated, and vice versa. For example, you could bind a model.name property to 
textPield.text. Users of the API need to specify howto read and write model.name and 
textPield.text, and key paths capture just that. 

We also need a way to observe changes to the properties. We use the key-value observing 
mechanism in Cocoa for this, which means that this example will only work with classes 
and only on Apple platforms. Foundation provides a new type-safe KVO API that hides 
the stringly typed world of Objective-C key paths. The NSObject method 
observe(_:options:changeHandler:) observes a key path (passed in as a strongly typed 
Swift key path) and calls the change handler whenever the property has changed. Don’t 
forget to mark any property you want to observe as @objc dynamic, otherwise KVO won’t 
work. 

Our goal is to implement a two-way binding between two NSObjects, but let’s start with a 
one-way binding: whenever the observed property of self changes, we change the other 
object as well. Key paths allow us to make this code generic over the specific properties 
involved: the caller specifies the two objects and the two key paths, and this method 
takes care of the rest: 


extension NSObjectProtocol where Self: NSObject { 
func observe<A, Other>(_ keyPath: KeyPath<Self, A>, 
writeTo other; Other, 

_ otherKeyPath: ReferenceWritableKeyPath<Other, A>) 

-> NSKeyValueObservation 

where A: Equatable, Other: NSObjectProtocol 

{ 

return observe(keyPath, options: .new) {change in 
guard let newValue = change.newValue, 
other[keyPath: OtherKeyPath] != newValue else { 
return //prevent endless feedback loop 

} 

otherjkeyPath: OtherKeyPath] = newValue 

} 

} 

} 

There’s a lot to unpack in this code snippet. First of all, we define this method on every 
subclass of NSObject, and by extending the NSObjectProtocol instead of NSObject, we’re 
allowed to use Self. ReferenceWritableKeyPath is just like WritableKeyPath, but it also 
allows us to write reference variables (like other) that are declared using let. (We’ll go 
into more details on that later.) To avoid unnecessary writes, we only write to other 
when the value has changed. The NSKeyValueObservation return value is a token the 
caller can use to control the lifetime of the observation: observation stops either when 
this object gets deallocated or when the caller calls its invalidate method. 

Given observe(_:writeTo:_:), two-way binding is straightforward: we call observe on both 
objects and return both observation tokens: 

extension NSObjectProtocol where Self: NSObject { 
func bind<A, Other>(_ keyPath: ReferenceWritableKeyPath<Self,A>, 
to other: Other, 

_ OtherKeyPath: ReferenceWritableKeyPath<Other,A>) 

-> (NSKeyValueObservation, NSKeyValueObservation) 
where A: Equatable, Other: NSObject 

{ 

let one = observe(keyPath, writeTo: other, otherKeyPath) 
let two = other.observe(otherKeyPath, writeTo: self, keyPath) 
return (one,two) 

} 

} 


Nowwe can construct two different objects. Sample and MyObj, and bind the name and 
test properties to each other: 

final class Sample: NSObject { 

@objc dynamic var name: String = 

} 

class MyObj: NSObject { 

@objc dynamic var test: String = 

} 

let sample = SampleO 
let other = MyObjO 

let observation = sample.bind(\Sample.name, to: other, \.test) 

sample.name = ''NEW 

other.test/^NEW 

other.test = "HI" 

sample.name//H/ 

At the time of writing, key paths are a very new addition to Swift. We expect that many 
more interesting use cases wiii pop up in the future. 


If you come from functionai programming, writabie key paths might remind 
you of lenses. They are cioseiy reiated: from a WritableKeypath<Root, Value>, 
you can create a Lens<Root, Value>. Lenses are usefui in pure functionai 
ianguages iike Haskeii or PureScript, but they aren’t neariy as useful in Swift, 
because Swift has mutability built in. 


The Key Path Hierarchy 

There are five different types for key paths, each adding more precision and 
functionality to the previous one: 

-> An AnyKeyPath is similar to a function (Any) -> Any? 

-> A PartialKeyPath<Source> is similar to a function (Source) -> Any? 

-> A KeyPath<Source, Target> is similar to a function (Source) -> Target 



-> A WritableKeyPath<Source, Target> is similar to a pair of functions: 

(Source) -> Target and (inout Source, Target) -> () 

-> A ReferenceWritableKeyPathtSource, Target> is similar to a pair of functions: 
(Source) -> Target and (Source, Target) -> (). The second function can update a 
Source value with Target, and works only when Source is a reference type. The 
distinction between WritableKeyPath and ReferenceWritableKeyPath is necessary 
because the setter for the former has to take its argument inout. 

This hierarchy of key paths is currently implemented as a class hierarchy. Ideally, these 
would be protocols, but Swift 4’s generics system lacks some features to make this 
feasible. The class hierarchy is intentionally kept closed to facilitate changing this in a 
future release without breaking existing code. 

As we’ve seen before, key paths are different from functions: they conform to Hashable, 
and in the future they’ll probably conform to Codable as well. This is why we say 
AnyKeyPath is similar to a function (Any) -> Any. While we can convert a key path into its 
corresponding function(s), we can’t always go in the other direction. 


Key Paths Compared to Objective-C 

In Foundation and Objective-C, key paths are modeled as strings (we’ll call these 
Foundation key paths to distinguish them from Swift’s key paths). Because Foundation 
key paths are strings, they don’t have any type information attached to them. In that 
sense, they’re similar to AnyKeyPath. If a Foundation key path is misspelled, is not well 
formed, or if the types don’t match, the program will probably crash. (The #keyPath 
directive in Swift helps a little with the misspelling; the compiler can check if a property 
with the specified name exists.) Swift’s KeyPath, WritableKeypath, and 
ReferenceWritableKeyPath are correct by construction: they can’t be misspelled and 
they don’t allow for type errors. 

Many Cocoa APIs use (Foundation) key paths when a function might have been better. 
This is partially a historical artifact: anonymous functions (or blocks, as Objective-C 
calls them) are a relatively recent addition, and key paths have been around much 
longer. Before blocks were added to Objectlve-C, it wasn’t easy to represent something 
similar to the function {$0.add ress.street}, except by using a key path: 

"address.street". 



Future Directions 


Key paths are still under active discussion, and it’s likely they’ll become more capable in 
the future. One possible feature is serialization through the Codable protocol. This 
would allow us to persist key paths on disk, send them over the network, and so on. 

Once we have access to the structure of the key paths, this enables introspection. For 
example, we could use the structure of a key path to construct well-typed database 
queries. If types could automatically provide an array of key paths to their properties, 
this could serve as the basis for runtime reflection APIs. 

Support for allowing subscript expressions in key paths is also planned, but the 
implementation didn’t quite make the cut for Swift 4.0. In a future release, you’ll 
probably be able to write things like \[String].[n].count to form a key path to an array’s 
n-th element’s character count, or\[String: String].[''name'']?.isEmpty for akey path to a 
property of a value that’s stored in a dictionary under the specified key. The Swift team 
has also expressed interest in supporting arbitrary function calls in key path expressions 
(provided those functions don’t capture mutable state). For example, it’s “not fair’’ that 
\MyObject.firstFiveElements and \My0bject[3] are valid KeyPaths, but 
\My0bject.prefix(5) isn’t. 


Automatic Closures 


We’re all familiar with how the logical AND operator && evaluates its arguments. It first 
evaluates its left operand and immediately returns if that evaluation yields false. Only if 
the left operand evaluates to true is the right operand evaluated. After all, if the left 
operand evaluates to false, there’s no way the entire expression can evaluate to true. 

This behavior is called short-circuiting. For example, if we want to check if a condition 
holds for the first element of an array, we could write the following code: 

let evens = [2,4,6] 

if levens.isEmpty && evens[0] > 10 { 

//Perform some work 

} 

In the snippet above, we rely on short-circuiting: the array lookup happens only if the 
first condition holds. Without short-circuiting, this code would crash on an empty array. 


A better way to write this particular example is to use an if let binding: 


if let first = evens.first, first > 10 { 
// Perform some work 

} 


This is another form of short-circuiting: the second condition is only evaluated 
if the first one succeeds. 


In almost all languages, short-circuiting for the && and || operators is built into the 
language. However, it’s often not possible to define your own operators or functions that 
have the same behavior. If a language supports first-class functions, we can fake 
short-circuiting by providing an anonymous function instead of a value. For example, 
let’s say we wanted to define an and function in Swift with the same behavior as the && 
operator: 

func and(_ 1: Bool, _ r: () -> Bool) -> Bool { 

guard I else { return false } 
return r() 

} 

The function above first checks the value of I and returns false if I evaluates to false. 

Only if I is true does it return the value that comes out of the closure r. Using it is a little 
bit uglier than using the && operator, though, because the right operand now has to be a 
function: 

if and(!evens.isEmpty, {evens[0] > 10}) { 

//Perform some work 

} 

Swift has a nice feature to make this prettier. We can use the ©autoclosure attribute to 
tell the compiler that it should wrap a particular argument in a closure expression. The 
definition of and is almost the same as above, except for the added ©autoclosure 
annotation: 

func and(_ 1: Bool, _ r: @autoclosure () -> Bool) -> Bool { 
guard I else { return false } 
return r() 

} 



However, the usage of and is now much simpler, as we don’t need to wrap the second 
parameter in a closure. We can just call it as if it took a regular Bool argument, and the 
compiler transparently wraps the argument in a closure expression: 

if and(!evens.isEmpty, evensjO] > 10) { 

//Perform some work 

} 

This allows us to define our own functions and operators with short-circuiting behavior. 
For example, operators like ?? and !? (as defined in the chapter on optlonals) are now 
straightforward to write. In the standard library, functions like assert and fatalError also 
use autoclosures in order to only evaluate the arguments when really needed. By 
deferring the evaluation of assertion conditions from the call sites to the body of the 
assert function, these potentially expensive operations can be stripped completely in 
optimized builds where they’re not needed. 

Autoclosures can also come in handy when writing logging functions. For example, 
here’s how you could write your own log function, which only evaluates the log message 
if the condition is true: 

func log(ifFalse condition: Bool, 
message: @autoclosure () -> (String), 

file: String = #file, function: String = #function, line: Int = #line) 

{ 

guard Icondition else { return } 

print(" Assertion failed :\(message()),\(file):\(function) (line \(line))") 

} 

This means you can perform expensive computations in the expression you pass as the 
message argument without incurring the evaluation cost if the value isn’t used. The log 
function also uses the debugging identifiers #file, #function, and #line. They’re 
especially useful when used as a default argument to a function, because they’ll receive 
the values of the filename, function name, and line number at the call site. 

Use autoclosures sparingly, though. Their behavior violates normal expectations — for 
example, if a side effect of an expression isn’t executed because the expression is 
wrapped in an autoclosure. To quote Apple’s Swift book: 


Overusing autoclosures can make your code hard to understand. The context 
and function name should make it clear that evaluation is being deferred. 


The ©escaping Annotation 

As we saw in the previous chapter, we need to be careful about memory when dealing 
with functions. Recall the capture list example, where we needed to mark view as weak 
in order to prevent a reference cycle: 

window?.onRotate = {[weak view] in 
printC'We now also need to update the view:\(view)'') 

} 

However, we never marked anything as weak when we used functions like map. This 
isn’t necessary because the compiler knows that map will never create a reference cycle: 
it’s executed synchronously and the closure never leaves map’s scope. The difference 
between the closure we store in onRotate and the closure we pass to map is that the first 
closure escapes. 

A closure that’s stored somewhere to be called later (for example, after a function 
returns) is said to be escaping. The closure that gets passed to map only gets used 
directly within map. This means that the compiler doesn’t need to change the reference 
count of the captured variables. 

Closures are non-escaping by default. If you want to store a closure for later use, you 
need to mark the closure argument as ©escaping. The compiler will verify this: unless 
you mark the closure argument as ©escaping, it won’t allow you to store the closure (or 
return it to the caller, for example). In the sort descriptors example, there were multiple 
function parameters that required the ©escaping attribute: 

func sortDescriptor<Value, Key>( 
key: ©escaping (Value) -> Key, 

by arelnIncreasingOrder; ©escaping (Key, Key) -> Bool) 

-> SortDescriptor<Value> 

{ 

return {arelnlncreasingOrder(key($0), key($1))} 

} 


Before Swift 3, it was the other way around: escaping was the defauit, and 
you had the option to mark a ciosure as ©noescape. The current behavior 
is better because it’s safe by defauit: a function argument now needs to be 
expiicitiy annotated to signai the potentiai for reference cycles. The ©escaping 
annotation serves as a warning to the developer using the function. This is also 
the reason why the compiler enforces the use of self, for accessing members in 
escaping closures — the developer must explicitly opt into capturing a strong 
reference. Lastly, non-escaping closures can be optimized much better by the 
compiler, making the fast path the norm you have to explicitly deviate from if 
necessary. 


Note that the non-escaping-by-default rule only applies to function parameters, and 
then only for function types in immediate parameter position. This means stored 
properties that have a function type are always escaping (which makes sense). 
Surprisingly, the same is true for functions that are used as parameters, but are wrapped 
in some other type, such as a tuple or an optional. Since the closure is no longer an 
immediate parameter in this case, it automatically becomes escaping. As a consequence, 
you can’t write a function that takes a function argument where the parameter is hoth 
optional and non-escaping. In many situations, you can avoid making the argument 
optional hy providing a default value for the closure. If that’s not possible, a workaround 
is to use overloading to write two variants of the function — one with an optional 
(escaping) function parameter, and one with a non-optional, non-escaping parameter: 

func transform(_ input: Int, with f: ((Int) -> Int)?) -> Int { 
printC'Using optional overload") 
guard let f = f else { return input} 
return f(input) 

} 

func transform(_ input: int, with f: (int) -> int) -> int { 
printC'Using non-optional overload") 
return f(input) 

} 

This way, calling the function with anil argument (or a variable of optional type) will use 
the optional variant, whereas passing a literal closure expression will invoke the 
non-escaping, non-optional overload. 

transform(10, with: nil) /'Using optional overload 
transform(10) {$0 * $0} /' Using non-optional overload 



withoutActuallyEscaping 


You may run into a situation where you know that a ciosure doesn’t escape but the 
compiler can’t prove it, forcing you to add an ©escaping annotation. In this example, we 
extend Array with a method that returns true if and only if all elements satisfy the given 
predicate. We already defined this method in the chapter on built-in collections. 

Let’s try a different implementation here: we first create a lazy view of the array (not to 
be confused with the lazy properties we discussed above) before applying a filter and 
checking whether any element got through the filter (i.e. whether at least one element 
didn’t satisfy the predicate). The purpose of doing the operations lazily is that 
evaluation can stop as soon as the first mismatch is found. Our first attempt at 
implementing this fails to compile because the filter method on a lazy collection view 
takes an escaping closure: 

extension Array { 

func all(matching predicate: (Element) -> Bool) -> Bool { 

// Error: parameter 'predicate' is implicitly non-escaping 
return self.lazy.filter({ !predicate($0) }).isEmpty 

} 

} 

We could fix this by annotating the parameter with ©escaping, but in this case we know 
the closure won’t escape because the lifetime of the lazy collection view is bound to the 
lifetime of the function. Swift provides an escape hatch for situations like this in the 
form of the withoutActuallyEscaping function. It allows you to pass a non-escaping 
closure to a function that expects an escaping one. This compiles and works correctly: 

extension Array { 

func all(matching predicate: (Element) -> Bool) -> Bool { 
return withoutActuallyEscaping(predicate) {escapablePredicate in 
self. lazy.fiIter {!escapablePredicate($0) }.isEmpty 

} 

} 

} 

let areAllEven = [1,2,3,4].all {$0 % 2 ==0}// false 
let areAllOneDigit = [1,2,3,4].all {$0 < ^0} //true 

Be aware that you’re entering unsafe territory by using withoutActuallyEscaping. 
Allowing the copy of the closure to escape from the call to withoutActuallyEscaping 
results in undefined behavior. 


Recap 

Functions are first-class values in Swift. Treating functions as data can make our code 
more fiexibie. We’ve seen how we can repiace runtime programming with simpie 
functions. We’ve compared different ways to impiement delegates. We’ve looked at 
mutating functions and inout parameters, as weli as computed properties (which realiy 
are a speciai kind of function). Finally, we’ve discussed the @autoclosure and 
©escaping attributes. In the chapters on generics and protocols, we’ll come up with 
more ways to use functions in Swift to gain additional flexibility. 



Strings 




All modern programming languages have support for Unicode strings, but that often 
only means that the native string type can store Unicode data — it’s not a promise that 
simple operations like getting the length of a string will return “sensible” results. In fact, 
most languages, and in turn most string manipulation code written in those languages, 
exhibit a certain level of denial about Unicode’s inherent complexity. This can lead to 
some unpleasant bugs. 

Swift’s string implementation goes to heroic efforts to be as Unicode-correct as possible. 
A String in Swift is a collection of Character values, where a Character is what a human 
reader of a text would perceive as a single character, regardless of how many Unicode 
code points it’s composed of. As a result, all standard Collection operations like count or 
prefix(5) work on the level of user-perceived characters. 

This is great for correctness, but it comes at a price, mostly in terms of unfamiliarity; if 
you’re used to manipulating strings with integer indices in other languages. Swift’s 
design will seem unwieldy at hrst, leaving you wondering. Why can’t I write str[999] to 
access a string’s one-thousandth character? Why doesn’t str[idx-t1] get the next 
character? Why can’t I loop over a range of Character values such as ''a"..."z''? It also has 
performance implications: String does not support random access, i.e. jumping to an 
arbitrary character is not an 0(1) operation. It can’t be — when characters have variable 
width, the string doesn’t know where the character is stored without looking at all 
characters that come before it. 

In this chapter, we’ll discuss the string architecture in detail, as well as some techniques 
for getting the most out of Swift strings in terms of functionality and performance. But 
we’ll start with an overview of the required Unicode terminology. 


Unicode, Or: No More Fixed Width 

Things used to be so simple. ASCII strings were a sequence of integers between 0 and 127. 
If you stored them in an 8-bit byte, you even had a bit to spare! Since every character was 
of a hxed size, ASCII strings could be random access. 

But ASCII wasn’t enough if you were writing in anything other than English or for a 
non-U.S. audience; other countries and languages needed other characters (even 
English-speaking Britain needed a £ sign). Most of them needed more characters than 
would ht into seven bits. ISO 8859 takes the extra bit and defines 16 different encodings 
above the ASCII range, such as Part 1 (ISO 8859-1, aka Latin-1), covering several Western 
European languages; and Part 5, covering languages that use the Cyrillic alphabet. 



This is stiil limiting, though. If you want to use ISO 8859 to write in Turkish about 
Ancient Greek, you’re out of luck, since you’d need to pick either Part 7 (Latin/Greek) or 
Part 9 (Turkish). And eight bits is still not enough to encode many languages. For 
example. Part 6 (Latin/Arabic) doesn’t include the characters needed to write 
Arable-script languages such as Urdu or Persian. Meanwhile, Vietnamese — which is 
based on the Latin alphabet but with a large number of diacritic combinations — only 
fits into eight bits by replacing a handful of ASCII characters from the lower half. And 
this isn’t even an option for other East Asian languages. 

When you run out of room with a fixed-width encoding, you have a choice: either 
increase the size, or switch to variable-width encoding. Initially, Unicode was defined as 
a 2-byte fixed-width format, now called UCS-2. This was before reality set in, and it was 
accepted that even two bytes would not be sufficient, while four would be horribly 
inefficient for most purposes. 

So today, Unicode is a variable-width format, and it’s variable in two different senses: in 
the combining of code units into Unicode scalars, and in the combining of scalars into 
characters. 

Unicode data can be encoded with many different widths of code unit, most commonly 8 
(UTF-8) or 16 (UTF-16) bits. UTF-8 has the added benefit of being backwardly compatible 
with 8-blt ASCII — something that’s helped it overtake ASCII as the most popular 
encoding on the web. Swift represents UTF-16 and UTF-8 code units as UInti 6 and Ulnt8 
values, respectively (aliased as Unicode.UTF16.CodeUnit and Unicode.UTFS.CodeUnit). 

A code point in Unicode is a single value in the Unicode code space with a possible value 
from 0 to 0x1 OFFFF (in decimal: 1,114,111). Only about 137,000 of the 1.1 million available 
code points are currently in use, so there’s a lot of room for more emoji. A given code 
point might take a single code unit if you’re using UTF-32, or it might take between one 
and four if you’re using UTF-8. The first 256 Unicode code points match the characters 
found in Latin-1. 

Unicode scalars are almost, but not quite, the same as code points. They’re all the code 
points except the 2,048 surrogate code points in the range 0-xD8000xDFFF, i.e. the code 
points used for the leading and trailing codes that indicate pairs in UTF-16 encoding. 
Scalars are represented in Swift string literals as "\u{xxxx}'', where xxxx represents hex 
digits. So the euro sign can be written in Swift as either or "\u{20AC}". The 
corresponding Swift type is Unicode.Scalar, which is a wrapper around a Ulnt3 2 value. 

To represent each Unicode scalar by a single code unit, you’d need a 21-bit encoding 
scheme (which usually gets rounded up to 32-bit, i.e. UTF-32), but even that wouldn’t get 



you a fixed-width encoding: Unicode is stili a variabie-width format when it comes to 
“characters.” What a user might consider “a singie character” — as dispiayed on the 
screen — might require muitipie scaiars composed together. The Unicode term for such 
a user-perceived character is (extended) grapheme cluster. 

The ruies for how scaiars form grapheme clusters determine how text is segmented. For 
example, if you hit the backspace key on your keyboard, you expect your text editor to 
delete exactly one grapheme cluster, even if that “character” is composed of multiple 
Unicode scalars, each of which may use a varying number of code units in the text’s 
representation in memory. Grapheme clusters are represented in Swift by the Character 
type, which can encode an arbitrary number of scalars, as long as they form a single 
user-perceived character. We’ll see some examples of this in the next section. 


Grapheme Clusters and Canonical 
Equivalence 

Combining Marks 

A quick way to see how String handles Unicode data is to look at the two different ways 
to write e. Unicode defines U+00E9, Latin small letter e with acute, as a single value. But 
you can also write it as the plain letter e, followed by U+0301, combining acute accent. In 
both cases, what’s displayed is e, and a user probably has a reasonable expectation that 
two strings displayed as “resume” would not only be equal to each other but also have a 
“length” of six characters, no matter which technique was used to produce the e in either 
one. They would be what the Unicode specification describes as canonically equivalent. 

And in Swift, this is exactly the behavior you get: 

let single = "Pok\u{00E9}mon" //Pokemon 
let double = ''Poke\u{0301}mon" //Pokemon 

They both display identically: 

(single,double)/'f'Pokemon" "Pokemon") 

And both have the same character count: 


single.count//7 


double.count/// 


Consequently, they also compare equal: 
single == double//true 

Only if you drop down to a view of the underlying representation can you see that 
they’re different: 

single.utfl 6.count // 7 
double.utf16.count//8 

Contrast this with NSString in Foundation: the two strings aren’t equal, and the length 
property — which many programmers probably use to count the number of characters 
to be displayed on the screen — gives different results: 

let nssingle = single as NSString 

nssingle.length Z'7 

let nsdouble = double as NSString 

nsdouble.length //8 

nssingle == nsdouble/^ false 

Here, == is dehned as the version for comparing two NSObjects: 

extension NSObject: Equatable { 
static func = = (lhs: NSObject, rhs: NSObject) -> Bool { 
return Ihs.isEqual(rhs) 

} 

} 

In the case of NSString, this wili do a literai comparison on the ievei of UTF-16 code 
units, rather than one accounting for equivalent but differently composed characters. 
Most string APIs in other ianguages work this way too. If you really want to perform a 
canonical comparison, you must use NSString.compare(_:). Didn’t know that? Enjoy 
your future undiagnosable bugs and grumpy international user base. 

Of course, there’s one big benefit to just comparing code units: it’s faster! This is an 
effect that can still be achieved with Swift strings, via the utfl 6 view: 

single.utfl 6.elementsEqual(double.utf16) // false 


Why does Unicode support multiple representations of the same character at all? The 
existence of precomposed characters is what enables the opening range of Unicode code 
points to be compatible with Latin-1, which already had characters like e and n. While 
they might be a pain to deal with, it makes conversion between the two encodings quick 
and simple. 

And ditching precomposed forms wouldn’t have helped anyway, because composition 
doesn’t just stop at pairs; you can compose more than one diacritic together. For 
example, Yoruba has the character 6, which could be written three different ways: by 
composing 6 with a dot, or by composing o with an acute, or by composing o with both 
an acute and a dot. And for that last one, the two diacritics can be in either order! So 
these are all equal: 

let chars: [Character] = [ 

''\u{1 ECD}\u{300}'', //p 

"\u{F2}\u{323}", //6 

''\u{6F}\u{323}\u{300}'', // 6 
''\u{6F}\u{300}\u{323}'' //6 

] 

let allEqual = chars.dropFirstQ.all {$0 == chars.first } //true 

(The all(matching:) method checks if the condition is true for all elements in a sequence 
and is defined in the chapter on built-in collections.) 

In fact, some diacritics can be added ad Infinitum. A famous internet meme illustrates 
this nicely: 


let zalgo = ''s6^'' 


zalgo.count/74 
zalgo. utfl S.count // 36 

In the above, zalgo.count (correctly) returns 4, while zalgo.utfl 6.count returns 36. And if 
your code doesn’t work correctly with internet memes, then what good is it, really? 


Unicode’s grapheme breaking ruies even affect you when ail strings you deal with are 
pure ASCII: CR+LF, the character pair of carriage return and line feed that’s commonly 
used as a line break on Windows, is a single grapheme: 

//CR+LFis a single Character 
let crlf = "\r\n" 
crlf.count// 7 


Emoji 

Strings containing emoji can also be surprising in many other languages. Many emoji 
are assigned Unicode scalars that don’t fit in a single UTF-16 code unit. Languages that 
represent strings as collections of UTF-16 code units, such as Java or C#, would say that 
the string " ^ " is two “characters” long. Swift handles this case correctly: 


let oneEmoji = "d" //U+1F602 
oneEmoji.count// 7 


Notice that the important thing is how the string is exposed to the program, 
not how it’s stored in memory. Swift also uses UTF-16 as its internal encoding 
for non-ASCII strings, but that’s an implementation detail. The public API is 
based on grapheme clusters. 


Other emoji are composed of multiple scalars. An emoji flag is a combination of two 
r egional indicator letters that correspond to an ISO country code. Swift treats it correctly 
as one Character: 


let flags = "■■I'' 
flags.count // 2 

To inspect the Unicode scalars a string is composed of, use the unicodeScalars view. 
Here, we format the scalar values as hex numbers in the common format for code points: 

flags.unicodeScalars.map { 

''U-l-\(String($0.value, radix: 16, uppercase: true))" 

} 

//["U+1FTE7", "U+1F1F7", "U+1F1F3", "U+1F1FF"] 




Skin tones combine a base character such as S with one of five skin tone modifiers (e.g. 
I , or the type-4 skin tone modifier) to yield the finai emoji (e.g. 0 ). Again, Swift 
handies this correctiy: 


let skinTone = "® " // 0 -l- H 
skinTone.count // 7 

This time, iet’s use a Foundation API to appiy an ICU string transform that converts 
Unicode scaiars to their officiai Unicode names: 

extension StringTransform { 

static let toUnicodeName = StringTransform(rawValue: "Any-Name") 

} 

extension Unicode.Scalar { 

///The scalar's Unicode name, e.g. "LATIN CAPITAL LETTER A". 
var unicodeName: String { 

// Force-unwrapping is safe because this transform always succeeds 

let name = String(self).applyingTransform(.toUnicodeName, reverse: false)! 

// The string transform returns the name wrapped in "\\N{...}". Remove those. 
let prefixPattern = ''\\N{'' 
let suffixPattern = 

let prefixLength = name.hasPrefix(prefixPattern) ? prefixPattern.count: 0 
let suffixLength = name.hasSuffix(suffixPattern) ? suffixPattern.count :0 
return String(name.dropFirst(prefixLength).dropLast(suffixLength)) 

} 

} 

skinTone.unicodeScalars.map { $0. unicodeName} 

//["GIRL", "EMOJI MODIFIER FITZPATRICK TYPE-4"] 

The essential part of this code snippet is the applyingTransform(.toUnicodeName, ...) cali. 
The remaining iines ciean up the name returned from the transform method by 
removing the wrapping braces. We code this defensiveiy: we first check whether the 
string matches the expected pattern and compute the number of characters to strip from 
the start and end. If the format returned by the transform method changes in the future, 
it’s better to return the string unchanged than to remove characters we didn’t anticipate. 
Notice how we use the standard Collection methods dropFirst and dropLast to perform 
the stripping operation. This is a good exampie of how you can manipuiate a string 



without doing manual index calculations. It’s also efficient because dropFirst and 
dropLast return a Substring, which is a slice of the original string. No new memory 
allocations are needed until the final step when we create a new String from the 
substring. We’ll have more to say about substrings later in this chapter. 

Emoji depicting families and couples, such as ga and , present another challenge to 
the Unicode standards body. Due to the countless possible combinations of genders and 
the number of people in a group, providing a separate code point for each variation is 
problematic. Combine this with a distinct skin tone for each person and it becomes 
impossible. Unicode solves this by specifying that these emoji are actually sequences of 
multiple emoji, combined with the invisible zero-width joiner (ZWJ) character (U+200D). 
So the family gQ is really man + ZWJ + woman ^ + ZWJ + girl jK + ZWJ + boy 
The ZWJ serves as an indicator to the operating system that it should use a single glyph 
if available. 

You can verify that this is really what’s going on: 
let familyl = "gS" 

letfamily2 = ''#\u{200D}|i\u{200D}f®\u{200D}#'' 
familyl == familyZ/^true 

And once again. Swift is smart enough to treat such a sequence as a single Character: 

familyl .count// 7 
family2.count7 

New emoji for professions introduced in 2016 are ZWJ sequences too. For example, the 
female firefighter ft is composed of woman ft| + ZWJ +fire engine iiS , and the male 
health worker is a sequence of man IP + ZWJ + staff of aesculapius f . 

Rendering these sequences into a single glyph is the task of the operating system. On 
Apple platforms in 2017, the OS includes glyphs for the subset of sequences the Unicode 
standard lists as “ recommended for general interchange ” (RGI), i.e. the ones “most likely 
to be widely supported across multiple platforms.” When no glyph is available for a 
syntactically valid sequence, the text rendering system falls back to rendering each 
component as a separate glyph. Notice that this can cause a mismatch “in the other 
direction” between user-perceived characters and what Swift sees as a grapheme cluster; 
all examples up until now were concerned with programming languages overcounting 
characters, but here we see the reverse. As an example, family sequences containing 
skin tones are currently not part of the RGI subset. But even if the operating system 



renders such a sequence as multiple glyphs. Swift still counts it as a single Character 
because the Unicode text segmentation rules are not concerned with rendering: 

// Family with skin tones is rendered as multiple glyphs 
//on most platforms in 2017 

letfamilyS = ''|>\u{200D}fii\u{200D}®\u{200D}(W'' 

//But Swift still counts it as a single Character 
familyS.count// 7 

Microsoft can already render this and other variations as a single glyph, hy the way, and 
the other OS vendors will almost certainly follow soon. But the point still stands: no 
matter how carefully a string API is designed, text is so complicated that it may never 
catch all edge cases. 


In the past. Swift had trouble keeping up with Unicode changes. Swift 3 
handled skin tones and ZWJ sequences incorrectly because its grapheme 
breaking algorithm was based on an old version of the Unicode standard. As 
of Swift 4, Swift uses the operating system’s ICU library. As a result, your 
programs will automatically adopt new Unicode rules as users update their 
OSes. The other side of the coin is of course that you can’t rely on users seeing 
the same behavior you see during development. 


In the examples we discussed in this section, we treated the length of a string as a proxy 
for all sorts of things that can go wrong when a language doesn’t take the full complexity 
of Unicode into account. Just think of the gibberish a simple task such as reversing a 
string can produce in a programming language that doesn’t process strings by grapheme 
clusters when the string contains composed character sequences. This isn’t a new 
problem, but the emoji explosion has made it much more likely that bugs caused by 
sloppy text handling will come to the surface, even if your user base is predominantly 
English-speaking. And the magnitude of errors has increased as well: whereas a decade 
ago a botched accented character would cause an off-by-one error, messing up a modern 
emoji can easily cause results to be off by 10 or more “characters.” For example, a 
four-person family emoji is 11 (UTF-16) or 25 (UTF-8) code units long: 

familyl.count// 7 
familyl .utfl 6.count // 7 7 
familyl .utf8.count//25 



It’s not that other languages don’t have Unicode-correct APIs at all — most do. For 
instance, NSString has the enumerateSubstrings method that can be used to walk 
through a string by grapheme clusters. But defaults matter; Swift’s priority is to do the 
correct thing by default. And if you ever need to drop down to a lower level of 
abstraction. String provides views that let you operate directly on Unicode scalars or 
code units. We’ll say more about those below. 


Strings and Collections 

As we’ve seen. String Is a collection of Character values. In Swift’s first three years of 
existence. String went back and forth between conforming and not conforming to the 
Collection protocol. The argument for not adding the conformance was that 
programmers would expect all generic collection-processing algorithms to be 
completely safe and Unicode-correct, which wouldn’t necessarily be true for all edge 
cases. 

As a simple example, you might assume that If you concatenate two collections, the 
resulting collection’s length would be the sum of the lengths of the two source 
collections. But this doesn’t hold for strings If a suffix of the first string forms a 
grapheme cluster with a prefix of the second string: 


let flagLetterJ = "il! " 

let flagLetterP = "S " 

let flag = flagLetterJ + flagLetterP 
flag.count // 7 

flag.count == flagLetterJ.count -I- flagLetterP.count // false 

To this end. String itself was not made a Collection in Swift 2 and 3; a 
collection-of-characters view was moved to a property, characters, which put it on a 
footing similar to the other collection views: unicodeScalars, utf8, and utfl 6. Picking a 
specific view prompted you to acknowledge you were moving into a 
“collection-processing” mode and that you should consider the consequences of the 
algorithm you were about to run. 

In practice, the loss In usability and learnabllity caused by this change turned out to 
vastly outweigh the gain in correctness for a few edge cases that are rarely relevant In 








real code (unless you’re writing a text editor). So String was made a Collection again In 
Swift 4. The characters view still exists, but only for backward compatibility. 


Bidirectional, Not Random Access 

However, for reasons that should be clear from the examples In the previous section. 
String is not a random-access collection. How could it be, when knowing where the 
character of a particular string is involves evaluating just how many Unicode scalars 
precede that character? For this reason. String conforms only to BidirectionalCollection. 
You can start at either end of the string, moving forward or backward, and the code will 
look at the composition of the adjacent characters and skip over the correct number of 
bytes. However, you need to iterate up and down one character at a time. 

Keep the performance Implications of this in mind when writing string-processing code. 
Algorithms that depend on random access to maintain their performance guarantees 
aren’t a good match for Unicode strings. Consider this String extension for generating a 
list of a string’s prefixes, which works by generating an integer range from zero to the 
string’s length and then mapping over the range to create the prefix for each length: 

extension String { 
var allPrefixesI: [Substring] { 
return (0... self. count). map(self. prefix) 

} 

} 

let hello = "Hello" 

hello.allPrefixesI // "H", "He", "Hel", "Hell", "Hello"] 


As simple as this code looks, it’s very inefficient. It first walks over the string once to 
calculate the length, which is fine. But then each of the n + 1 calls to prefix is another 
0(n) operation because prefix always starts at the beginning and has to work its way 
through the string to count the desired number of characters. Running a linear process 
inside another linear loop means this algorithm is accidentally ©(n^) — as the length of 
the string increases, the time this algorithm takes increases quadratically. 

If possible, an efficient string algorithm should walk over a string only once and then 
operate on string indices to denote the substrings it’s interested in. Here’s another 
version of the same algorithm: 


extension String { 


var aUPrefixes2: [Substring] { 
return [""] + self.indices.map {index in self]. ..index]} 

} 

} 


heUo.allPrefixes2 //"H" "He", "Hel", "Hell", "Hello"] 


This code also has to iterate over the string once to generate the indices collection. But 
once that’s done, the subscripting operation inside map is 0(1). This makes the whole 
algorithm 0(n). 


I The Prefixiterator we implemented in the collection protocols chapter solves 
the same problem in a generic way for all sequences. 


Range-Replaceable, Not Mutable 

string also conforms to RangeReplaceabieColiection. Here’s an example of how you’d 
replace part of a string by hrst identifying the appropriate range in terms of string 
indices and then calling repiaceSubrange. The replacement string can have a different 
length or could even be empty (which would be equivalent to calling removeSubrange): 

var greeting = "Hello, world!" 
if let comma = greeting.index(of:{ 
greeting]..<comma] /7He//o 

greeting.replaceSubrange(comma..., with: " again.") 

} 

greeting//He//o again. 

As always, keep in mind that results may be surprising if parts of the replacement string 
form new grapheme clusters with adjacent characters in the original string. 

One collection-like feature strings do not provide is that of MutableCollection. This 
protocol adds one feature to a collection — that of the single-element subscript set — in 
addition to get. This isn’t to say strings aren’t mutable — as we’ve just seen, they have 
several mutation methods. But what you can’t do is replace a single character using the 
subscript operator. The reason comes back to variable-length characters. Most people 
can probably intuit that a single-element subscript update would happen in constant 
time, as it does for Array. But since a character in a string may be of variable width. 


updating a single character could take linear time in proportion to the length of the 
string: changing the width of a single element would require shuffling all the later 
elements up or down in memory. Moreover, indices that come after the replaced index 
would become invalid through the shuffling, which is equally unintuitive. For these 
reasons, you have to use replaceSubrange, even if the range you pass in is only a single 
element. 


String Indices 

Most programming languages use Integers for subscripting strings, e.g. str[5] would 
return the sixth “character” of str (for whatever that language’s idea of a “character” is). 
Swift doesn’t allow this. Why? The answer should sound familiar to you by now: 
subscripting is supposed to take constant time (intuitively as well as per the 
requirements of the Collection protocol), and looking up the Character is impossible 
without looking at all hytes that come before it. 

String. Index, the index type used by String and its views, is an opaque value that 
essentially stores a byte offset from the beginning of the string. It’s still an 0(n) 
operation if you want to compute the index for the character and have to start at the 

beginning of the string, but once you have a valid index, subscripting the string with it 
now only takes 0(1) time. And crucially, finding the next index after an existing index is 
also fast because you can start at the existing index’s byte offset — you don’t need to go 
back to the beginning again. This is why iterating over the characters in a string in order 
(forward or backward) is efficient. 

String index manipulation is based on the same Collection APIs you’d use with any other 
collection. It’s easy to miss this equivalence since the collections we use by far the most 
— arrays — use integer Indices, and we usually use simple arithmetic to manipulate 
those. The index(after:) method returns the index of the next character: 

let s = ''abcdef 

let second = s.index(after: s.startindex) 
s[second] 

You can automate iterating over multiple characters in one go via the index(_:offsetBy:) 
method: 

//Advance 4 more characters 

let sixth = s.index(second, offsetBy: 4) 

s[sixth] 


If there’s a risk of advancing past the end of the string, you can add a limited By: 
parameter. The method returns nil if it hits the iimit before reaching the target index: 

let safeldx = s.index(s.startlndex, offsetBy: 400, limitedBy: s.endindex) 
safe\dx// nil 

This is undoubtediy more code than simpie integer indices wouid require, but again, 
that’s the point. If Swift ailowed integer subscripting of strings, the temptation to 
accidentaliy write horribiy inefficient code (e.g. by using integer subscripting inside a 
ioop) wouid be too big. 

Nevertheiess, to someone used to deaiing with fixed-width characters, working with 
strings in Swift seems chaiienging at first — how wiii you navigate without integer 
indices? And indeed, some seemingly simple tasks like extracting the first four 
characters of a string can turn into monstrosities like this one: 

s[..<s.index(s.startlndex, offsetBy: 4)] //abed 

But thankfully, being able to access the string via the Collection interface also means you 
have several helpful techniques at your disposal. Many of the methods that operate on 
Array also work on String. Using the prefix method, the same thing looks much clearer: 

s.prefix(4) abed 

(Note that either expression returns a Substring; you can convert it back into a String by 
wrapping it in a String, in it. We’ll talk more about substrings in the next section.) 

Iterating over characters in a string is easy without integer indices; just use a for loop. If 
you want to number each character in turn, use enumeratedQ: 

for (i, c) in s.enumeratedQ { 
print("\(i):\(c)'') 

} 

Or say you want to find a specific character. In that case, you can use index(of:): 

var hello = "Hello!" 
if let idx = hello.index(of: "I") { 
hello.insertfeontentsOf: ", world", at: idx) 

} 

hello//Hello, world! 


The insert(contentsOf:) method inserts another collection of the same element type (e.g. 
Character for strings) before a given index. This doesn’t have to be another String; you 
could insert an array of characters into a string just as easily. 


Substrings 

Like all collections. String has a specihc slice or Subsequence type named Substring. A 
substring is much like an ArraySlice: it’s a view of a base string with different start and 
end indices. Substrings share the text storage of their base strings. This has the huge 
beneht that slicing a string is a very cheap operation. Creating the firstWord variable in 
the following example requires no expensive copies or memory allocations: 

let sentence = "The quick brown fox jumped over the lazy dog." 
let firstSpace = sentence.index(of: " ") ?? sentence.endindex 
let firstWord = sentence[..<firstSpace] y/The 
type(of: firstWord) /^SuJbstnhg 

Slicing being cheap is especially important in loops where you iterate over the entire 
(potentially long) string to extract its components. Tasks like hnding all occurrences of a 
word in a text or parsing a CSV hie come to mind. A very useful string processing 
operation in this context is splitting. The split method is dehned on Collection and 
returns an array of subsequences (i.e. [Substring]). Its most common variant is defined 
like SO: 

extension Collection where Element: Equatable { 
public func split(separator: Element, maxSplits: Int = Int.max, 
omittingEmptySubsequences: Bool = true) -> [Subsequence] 

} 

You can use it like this: 

let poem = .. 

Over the wintry 
forest, winds howl in rage 
with no leaves to blow. 

(I II II 

let lines = poem.split(separator: "Xn") 

//["Over the wintry", "forest, winds howl in rage", "with no leaves to blow."] 
type(of: lines) //Array<Substring> 


This can serve a function similar to the components(separatedBy:) method String 
inherits from NSString, with added configurations for whether or not to drop empty 
components. Again, no copies of the input string are made. And since there’s another 
variant of split that takes a closure, it can do more than just compare characters. Here’s 
an example of a primitive word wrap algorithm, where the closure captures a count of 
the length of the line thus far: 

extension String { 

func wrapped(after; Int = 70) -> String { 
var i = 0 

let li nes = self.split(omittingEmptySubsequences: false) { 
character in 
switch character { 
case "Xn",'' " where i >= after: 
i = 0 

return true 
default: 

i += 1 

return false 

} 

} 

return lines.joined(separator: "Xn") 

} 

} 

sentence.wrapped(after: 15) 

/* 

The quick brown 
fox Jumped over 
the lazy dog. 

*/ 


Or, consider writing a version that takes a sequence of multiple separators: 

extension Collection where Element: Equatable { 
func splittS: Sequence>(separators: S) -> [Subsequence] 
where Element == S.Element 

{ 

return split {separators.contains($0)} 

} 

} 


This way, you can write the following: 

"Hello, world !''.split(separators: ",! ") // ["Hello", "world"] 


StringProtocol 

Substring has almost the same interface as String. This is achieved through a common 
protocol named StringProtocol, which both types conform to. Since almost the entire 
string API is dehned on StringProtocol, you can mostly work with a Substring as you 
would with a String. At some point, though, youTl have to turn your substrings back into 
String instances; like all slices, substrings are only intended for short-term storage, in 
order to avoid expensive copies during an operation. When the operation is complete 
and you want to store the results or pass them on to another subsystem, you should 
create a new String. You can do this by initializing a String with a Substring, as we do in 
this example: 

func lastWord(in input: String) -> String? { 

//Process the input, working on substrings 
let words = input.split(separators: " "]) 

guard let lastWord = words.last else { return nil } 

// Convert to String for return 
return String(lastWord) 

} 

lastWord(in: "one, two, three, four, five") //Optional("five") 

The rationale for discouraging long-term storage of substrings is that a substring always 
holds on to the entire original string. A substring representing a single character of a 
huge string will hold the entire string in memory, even after the original string’s lifetime 
would normally have ended. Long-term storage of substrings would therefore effectively 
cause memory leaks because the original strings have to be kept in memory even when 
they’re no longer accessible. 

By working with substrings during an operation and only creating new strings at the 
end, we defer copies until the last moment and make sure to only incur the cost of those 
copies that are actually necessary. In the example above, we split the entire (potentially 
long) string into substrings, but only pay the cost for a single copy of one short substring 
at the end. (Ignore for a moment that this algorithm isn’t efficient anyway; iterating 
backward from the end until we And the first separator would be the better approach.) 


Encountering a function that only accepts a Substri ng when you want to pass a String is 
less common — most functions should either take a String or any 
StringProtocol-conforming type. But if you do need to pass a String, the quickest way is 
to subscript the string with the range operator ... without specifying any bounds: 

// Substring with identical start and end index as the base string 
let substring = sentence!...] 

We already saw an example of this in the chapter on collection-protocols when we 
dehned the Words collection. 


The Substring type is new in Swift 4. In Swift 3, String.CharacterView used to be 
its own slice type. This had the advantage that users only had to understand a 
single type, but it meant that a stored substring would keep the entire original 
string buffer alive even after it normally would’ve been released. Swift 4 trades 
a small loss in convenience for cheap slicing operations and predictable 
memory usage. 

The Swift team does recognize that requiring explicit conversions from 
Substring to String is a little annoying. If this turns out to be a big problem in 
practical use, the team is considering wiring an implicit subtype relationship 
between Substring and String directly into the compiler, in the same way that 
Int is a subtype of Optional<lnt>. This would allow you to pass a Substring 
anywhere a String is expected, and the compiler would perform the conversion 
for you. 


You may be tempted to take full advantage of the existence of StringProtocol and convert 
all your APIs to take StringProtocol instances rather than plain Strings. But the advice of 
the Swift team is not to do that: 


Our general advice is to stick with Stri ng. Most APIs would be simpler and 
clearer just using String rather than being made generic (which itself can 
come at a cost), and user conversion on the way in on the few occasions that’s 
needed isn’t much of a burden. 


APIs that are extremely likely to he used with substrings, and at the same time aren’t 
further generalizable to the Sequence or Collection level, are an exception to this rule. 






An example of this in the standard library is the joined method. Swift 4 added an 
overload for sequences with StringProtocoi-conforming elements: 

extension Sequence where Element: StringProtocol { 

/// Returns a new string by concatenating the elements of the sequence, 

/// adding the given separator between each element. 
public func joined(separator: String = "") -> String 

} 

This lets you call joined directly on an array of substrings (which you got from a call to 
split, for example) without having to map over the array and copy every substring into a 
new string. This is more convenient and much faster. 

The number type initializers that take a string and convert it into a number also take 
StringProtocol values in Swift 4. Again, this is especially handy if you want to process an 
array of substrings: 

let commaSeparatedNumbers = "1,2,3,4,5'' 
let numbers = commaSeparatedNumbers 
.split(separator:flatMap {lnt($0)} 

//[1,2, 3, 4,5] 

Since substrings are intended to be short-lived, it’s generally not advisable to return one 
from a function unless we’re talking about Sequence or Collection APIs that return slices. 
If you write a similar function that only makes sense for strings, having it return a 
substring tells readers that it doesn’t make a copy. Functions that create new strings 
requiring memory allocations, such as uppercasedQ, should always return String 
instances. 

If you want to extend String with new functionality, placing the extension on 
StringProtocol is a good idea to keep the API surface between String and Substring 
consistent. StringProtocol is explicitly designed to be used whenever you would’ve 
previously extended String. If you want to move existing extensions from String to 
StringProtocol, the only change you should have to make is to replace any passing of self 
into an API that takes a concrete String with String(self). 

Keep in mind, though, that as of Swift 4, StringProtocol is not yet intended as a 
conformance target for your own custom string types. The documentation explicitly 
warns against it: 


Do not declare new conformances to StringProtocol. Only the String and 
Substring types of the standard library are valid conforming types. 


Allowing developers to write their own string types (with special storage or performance 
optimizations, for instance) is the eventual goal, but the protocol design hasn’t yet been 
flnaiized, so adopting it now may break your code in Swift 5. 


Code Unit Views 


Sometimes it’s necessary to drop down to a iower ievei of abstraction and operate 
directly on Unicode scalars or code units instead of grapheme ciusters. String provides 
three views for this: unicodeScalars, utf16, and utf8. Like String, these are bidirectionai 
collections that support ali the familiar operations. And like substrings, the views share 
the string’s storage; they simply represent the underlying bytes in a different way. 

There are a few common reasons why you’d need to work on one of the views. Firstly, 
maybe you actually need the code units, perhaps for rendering into a UTF-8-encoded 
webpage, or for interoperating with a non-Swift API that expects a particular encoding. 
Or maybe you need information about the string in a specific format. 

For exampie, suppose you’re writing a Twitter client. Whiie the Twitter API expects 
strings to be UTF-8-encoded, Twitter’s character counting aigorithm is based on 
N FC-normalized code points (i.e. scalars). So if you want to show your users how many 
characters they have ieft, this is how you could do it: 


let tweet = "Having X in a cafe\u{301} in ! • and enjoying the 
let characterCount = tweet 
.precomposedStringWithCanonicaiMapping 
.unicodeScalars.count 
//46 


(NFC normalization converts base ietters along with combining marks, such as the e pius 
accent in ''cafe\u{301}", into their precomposed form. The 
precomposedStringWithCanonicalMapping property is defined in Foundation.) 




UTF-8 is the de facto standard for storing text or sending it over the network. Since the 
utf8 view is a coilection, you can use it to pass the raw UTF-8 bytes to any other API that 
accepts a sequence of bytes, such as the initializers for Data or Array: 

let utf8 Bytes = Data(tweet.utf8) 
utf8Bytes.count // 62 

Note that the utf8 collection doesn’t include a trailing null byte. If you need a 
null-terminated representation, use the withCString method or the utf8CString property 
on String. The latter returns an array of bytes: 

let nullTerminatedUTF8 = tweet.utfSCString 
nullTerminatedUTF8.count/7 63 

The utfl 6 view has a special significance because Foundation APIs traditionally treat 
strings as collections of UTF-16 code units. While the NSString interface is transparently 
bridged to Swift.Stri ng, thereby handling the transformations implicitly for you, other 
Foundation APIs such as NSRegularExpression or NSAttributedString often expect input 
in terms of UTF-16 data. We’ll see an example of this in the next section. 

A second reason for using the code unit views is that operating on code units rather than 
fully composed characters can be faster. This is because the Unicode grapheme breaking 
algorithm is fairly complex and requires additional lookahead to identify the start of the 
next grapheme cluster. Traversing the String as a Character collection got much faster 
between Swift 3.0 and 4.0, however, so be sure to measure if the (relatively small) 
speedup is worth your losing Unicode correctness. As soon as you drop down to one of 
the code unit views, you must be certain that your specific algorithm works correctly on 
that basis. For example, using the UTF-16 view to parse JSON should be alright because 
all special characters the parser is interested in (such as commas, quotes, or braces) are 
representable in a single code unit; it doesn’t matter that some strings in the JSON data 
may contain complex emoji sequences. On the other hand, finding all occurrences of a 
word in a string wouldn’t work correctly on a code unit view if you want the search 
algorithm to find different normalization forms of the search string. To see just how big 
the speed difference can be, take a look at the performance section at the end of this 
chapter. 


No Random Access 

One desirable feature none of the views provides is random access. This is a change from 
Swift 3, where String.UTFI 6View view did conform to RandomAccessCollection (although 


only when you imported Foundation). This was possibie for just this view type because 
String uses UTF-16 or ASCII internally for its in-memory representation. This means the 
UTF-16 code unit would always be at the position in the buffer (even if the string 
was in “ASCII buffer mode” - it’s just a question of the width of the entries to advance 
over). And although this is still true in Swift 4.0, the internal format of String is supposed 
to be an implementation detail. The Swift team wants to keep the door open for adding 
different backing store types in the future. 

The consequence is that String and its views are a bad match for algorithms that require 
random access. The vast majority of string-processing tasks should work fine with 
sequential traversal, especially since an algorithm can always store substrings for 
fragments it wants to be able to revisit in constant time. If you absolutely need random 
access, you can always convert the UTF-8 or UTF-16 view into an array and work on that, 
as in Array(str.utf1 6) (again, at the price of sacrificing Unicode correctness). 


Index Sharing 

Strings and their views share the same index type. String.Index. This means you can use 
an index derived from the string to subscript one of the views. In the following example, 
we search the string for "e” (which consists of two scalars, the letter e and the combining 
accent). The resulting index refers to the first scalar in the Unicode scalar view: 

let pokemon = ''Poke\u{301}mon'' //Pokemon 
if let index = pokemon.index(of: "e") { 
let scalar = pokemon.unicodeScalarsjindex] //e 
String(scalar) //e 

} 

This works great as long as you go down the abstraction ladder, from characters to 
scalars to UTF-16 or UTF-8 code units. Going the other way can fail because not every 
valid index in one of the code unit views is on a Character boundary. In the following 
example, accessing the string with an index on a UTF-16 code unit boundary would trap: 

let family = "SS" 

// This initializer creates an index at a UTF-16 offset 
let someUTFI 6lndex = String.lndex(encodedOffset: 2) 

//family[sameUTF16lndex] //trap, invalid index 


string. Index has a set of methods (samePosition(in:)) and failable initializers 
(String.Index.init?(_:within:)) for converting indices between views. These return nil if the 
given index has no exact corresponding position in the specified view. For example, 
trying to convert the position of the combining accent in the scalars view to a valid index 
in the string fails because the combining character doesn’t have its own position in the 
string: 

if let accentindex = pokemon.unicodeScalars.index(of: ''\u{301}") { 
accentlndex.samePosition(in: pokemon)z/n// 

} 

Note that there’s a bug in Swift 4.0 that sometimes causes these conversions to wrongly 
succeed when working with complex emoji sequences, such as the family emoji we use 
above. noCharacterBoundary isn’t a valid position in the string, yet the return value is 
non-nil: 

let noCharacterBoundary = family.utf16.index(family.utf1 B.startindex, 
offsetBy: 3) 

// Not a valid index for the character view 
noCharacterBoundary.encodedOffset//3 

// Wrong! if let should fail because source index wos not on character boundary 
if let idx = String.lndex(noCharacterBoundary, within: family) { 

//Subscripting returns incomplete Character, this shouldn't happen 

family[idx] -''A 

} 

Until this is fixed, a reliable way to find the start of Character boundary is to use the 
Foundation method rangeOfComposedCharacterSequence: 

extension String.Index { 

func samePositionOnCharacterBoundary(in str: String) -> String.Index { 
let range = str.rangeOfComposedCharacterSequence(at: self) 
return range.lowerBound 

} 

} 

let validindex = 

noCharacterBoundary.samePositionOnCharacterBoundary(in: family) 

// Works 



family[validlndex] m 


Strings and Foundation 

Swift’s String type has a very close relationship with its Foundation counterpart, 
NSString. Any String instance can be bridged to NSString using the as operator, and 
Objective-C APIs that take or return an NSString are automatically translated to use 
String. But that’s not all. As of Swift 4.0, String still lacks a lot of functionality that 
NSString possesses. Since strings are such fundamental types and constantly having to 
cast to NSString would be annoying. String receives special treatment from the compiler: 
when you import Foundation, NSString members become directly accessible on String 
instances, making Swift strings significantly more capable than they’d otherwise be. 

Having the additional features is undoubtedly a good thing, but it can make working 
with strings somewhat confusing. For one thing, if you forget to import Foundation, you 
may wonder why some methods aren’t available. Foundation’s history as an Objective-C 
framework also tends to make the NSString APIs feel a little bit out of place next to the 
standard library, if only because of different naming conventions. Last but not least, 
overlap between the feature sets of the two libraries sometimes means there are two 
APIs with completely different names that perform nearly identical tasks. If you’re a 
long-time Cocoa developer and learned the NSString API before Swift came along, this is 
probably not a big deal, but it will be puzzling for newcomers. 

We’ve already seen one example — the standard library’s split method vs. 
components(separatedBy:) in Foundation — and there are numerous other mismatches: 
Foundation uses ComparisonResult enums for comparison predicates, while the 
standard library is designed around boolean predicates; methods like 
trimmingCharacters(in:) and components(separatedBy:) take a CharacterSet as an 
argument, which is an unfortuate misnomer in Swift (more on that later); the extremely 
powerful enumerateSubstrings(in:options:_:) method, which can iterate over a string in 
chunks of grapheme clusters, words, sentences, or paragraphs, deals with strings and 
ranges where a corresponding standard library API would use substrings. (The standard 
library could also expose the same functionality as a lazy sequence, which would be very 
cool.) 

The following example enumerates the words in a string. The callback closure is called 
once for every word found; 


let sentence = " 


The quick brown fox jumped \ 
over the lazy dog. 

II II II 

var words: [String] = [] 

sentence.enumerateSubstrings(in; sentence.startindex..., options: .byWords) 

{(word, range, _, _) in 
guard let word = word else { return } 
words.append(word) 

} 

words 

//["The", "quick", "brown", "fox", "jumped", "over", "the", "lazy", "dog"] 

To get an overview of all NSString members imported into String, check out the hie 
N SStringAPI.swift in the Swift source code repository. 


Other String-Related Foundation APIs 

Having said all that, native NSString APIs are mostly pleasant to use with Swift strings 
because most of the bridging work is done for you. Many other Foundation APIs that 
deal with strings are a lot trickier to use because Apple hasn’t (yet?) written special Swift 
overlays for them. Consider NSAttributedString, the Foundation class for representing 
rich text with formatting. To use attributed strings successfully from Swift, you have to 
be aware of the following: 

-> There are two classes, NSAttributedString for immutable strings, and 

NSMutableAttributedString for mutable ones. They have reference semantics, as 
opposed to the Swift standard for collections to have value semantics. 

-> Although all NSAttributedString APIs that originally take an NSString now take a 
Swift.String, the entire API is still based on NSString’s concept of a collection of 
UTFT6 code units. 

For example, the attributes(at: Int, effectiveRange: NSRangePointer?) method for 
querying the formatting attributes at a specific location expects an integer index 
(measured in UTFT6 units) rather than a String.Index, and the effectiveRange returned 
via pointer is an NSRange, not a Range<String.lndex>. The same is true for ranges you 
pass to NSMutableAttributedString.addAttribute(_:value:range:). 

NSRange is a structure that contains two integer helds, location and length: 



public struct NSRange { 
public var location: Int 
public var length: Int 

} 

In the context of strings, the fields specify a string segment in terms of UTF-16 code 
units. Swift 4 makes working with NSRange somewhat easier than in earlier versions 
because there are now initializers for converting between Range<String.lndex> and 
NSRange; this doesn’t make the extra code required to translate back and forth any 
shorter, however. Here’s an example of how you’d create and modify an attributed 
string: 


let text = "i#" Click here for more info." 
let linkTarget = 

URL(string: " https ://www.youtu be.com/watch?v=DLzxrzFCyOs")! 

// Object is mutable despite 'let' (reference semantics) 
let formatted = NSI\/lutableAttributedString(string:text) 

// Modify attributes of a part of the text 

if let linkRange = formatted.string.range(of: "Click here") { 

// Convert Swift range to NSRange 

//Note that the start of the range is 3 because the preceding emoji 

// character doesn't fit in a single UTF-16 code unit 

let nsRange = NSRangeflinkRange, in: formatted.string)/^f3, 10} 

//Add the attribute 

formatted.addAttribute(.link, value: linkTarget, range: nsRange) 

} 

This code adds a link to the "Click here" segment of the string. 

Querying the attributed string for the formatting attributes at a specific character 
position works like this (Including the cumbersome process of allocating a pointer to 
receive the effective range of the returned attributes as an out-parameter because 
Objective-C has no tuple return types): 

// Query attributes at start of the word "here" 

if let queryRange = formatted.string.range(of: "here"), 

// Get the character index in the UTF-1 6 view 

let utf16lndex = String.lndex(queryRange.lowerBound, 


within: formatted.string.utfl 6) 


{ 

// Convert index to UTF- 7 6 integer offset 

let utf160ffset = utfl 6lndex.encoded0ffset 

//Prepare NSRangePointer to receive effective attributes range 

var attributesRange = UnsafeMutablePointer<NSRange>.allocate(capacity: 1) 

defer { 

attributesRange.deinitialize(count: 1) 
attributesRange.deaUocate(capacity: 1) 

} 

//Execute query 

let attributes = formatted.attributes(at: utfl 60ffset, 
effectiveRange: attributesRange) 
attributesRange.pointee/7f3, 10} 

// Canvert NSRange back to Range<String. Index/ 

if let effectiveRange = Range(attributesRange.pointee, in: formatted.string) { 
// The substring spanned by the attribute 
formatted.string[effectiveRange] //Click here 

} 


We think you’ll agree that there’s still a long way to go before this code starts to feels like 
idiomatic Swift. 

Aside from NSAttributedString, other Foundation classes with very similar impedance 
mismatches include NSRegularExpression and the wonderful NSLinguisticTagger. 


Ranges of Characters 

Speaking of ranges, you may have tried to iterate over a range of characters and found 
that it doesn’t work: 

let lowercaseLetters = ("a" as Character). .."z" 
for c in lowercaseLetters {//Error 


} 


(The cast to Character is important because the defauit type of a string iiterai is String; 
we need to teil the type checker we want a Character range.) 

We taiked about the reason why this faiis in the chapter about buiit-in coiiections: 
Character doesn’t conform to the Strideable protocoi, which is a requirement for ranges 
to become countable and thus coiiections. Ali you can do with a range of characters is 
compare other characters against it, i.e. check whether a character is inside the range or 
not: 

lowercaseLetters.containsC'A”) // false 
lowercaseLetters.containsC'e") true 

It’s interesting that Swift’s defauit string ordering orders e between e and f, i.e. accented 
ietters are inside the range. Combine that with the fact that a single Character can 
contain an infinite number of combining marks, and it makes sense that the range can’t 
be countable: it contains an infinite (i.e. uncountable) number of possible characters. 

One type for which the notion of countable ranges does make sense is Unicode.Scalar, at 
least if you stick to ASCII or other well-ordered subsets of the Unicode catalog. Scalars 
have a well-defined order through their code point values, and there’s always a finite 
number of scalars between any two bounds. Unicode.Scalar isn’t Strideable by default, 
but we can add the conformance retroactively: 

extension Unicode.Scalar: Strideable { 
public typealias Stride = Int 

public func distance(to other: Unicode.Scalar) -> Int { 
return Int(other.value) - Int(self.value) 

} 

public func advanced(by n: Int) -> Unicode.Scalar { 
return Unicode.Scalar(Ulnt32(lnt(value) -t- n))! 

} 

} 

(We’re ignoring the fact that the surrogate code points OxDSOO to OxDFFF aren’t valid 
Unicode scalar values. Constructing a range that overlaps this region is a programmer 
error.) 

This allows us to create a countable range of Unicode scalars and use it as a very 
convenient way to generate an array of characters: 


let lowercase = ("a" as Unicode.Scalar). .."z" 
Array(lowercase.map(Character.init)) 

/* 

["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "I", "m", "n", 
"o", "p" "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"] 

*/ 


CharacterSet 

Let’s look at one last Interesting Foundation type, and that’s CharacterSet. We already 
mentioned in the built-in collections chapter that this struct should really be called 
UnicodeScalarSet because that’s what it is: an efficient data structure for representing 
sets of Unicode scalars. It is not at all compatible with the Character type. 

We can illustrate this by creating a set from a couple of complex emoji. It seems as 
though the set only contains the two emoji we put in, but testing for membership with a 
third emoji is successful because the firefighter emoji is really a sequence of woman + 
ZWJ +fire engine: 


let favoriteEmoji = CharacterSet(" nicodeScalars) 

// Wrong! Or is it? 

favoriteEmoji.containsC'ijiS'') //true 


CharacterSet provides a number of factory initializers like .alphanumerics or 
.whitespacesAndNewlines. Most of these correspond to official Unicode character 
c ategories (each code point is assigned a category, such as “Letter” or “Nonspacing 
Mark”). The categories cover all scripts, and not just ASCII or Latin-1, so the number of 
members in these predefined sets is often huge. The type conforms to SetAlgebra, which 
defines the interface for set operations such as membership testing and constructing 
unions or intersections. CharacterSet does not conform to Sequence or Collection, so we 
can’t easily count or iterate over all members in a set. 

The following example implements an alternative way of splitting a string into words 
using a CharacterSet via the UnicodeScalarView: 

extension String { 

func words(with charset: CharacterSet = .alphanumerics) -> [Substring] { 
return self.unicodeScalars.split { 




!charset.contams($0) 

}.map(Substring.init) 

} 

} 

let code = "struct Array<Element>: Collection {}" 
code.wordsO//["struct" "Array", "Element", "Collection"] 

This will break the string apart at every non-alphanumerlc character, giving us an array 
of UnicodeScalarView slices. We then turn them back into substrings via map, passing 
the substring initializer. The good news is, even after going through this fairly extensive 
pipeline, the string slices in words will still just be views onto the original string, so this 
should be more efficient than the components(separatedBy:) method (which returns an 
array of strings, and thus copies). 


Internal Structure of String and Character 

Like the other collection types in the standard library, strings are copy-on-write 
collections with value semantics. A String instance stores a reference to a buffer, which 
holds the actual character data. When you make a copy of a string (through assignment 
or by passing it to a function) or create substrings, all these instances share the same 
buffer. The character data is only copied when an instance gets mutated while it’s 
sharing its character buffer with one or more other instances. For more on 
copy-on-write, see the chapter on structs and classes. 

In Swift 4.0, String uses either 8-bit ASCII (if the string contains nothing but ASCII 
characters) or UTF-16 (if one or more non-ASCII characters are present) as its in-memory 
representation. You may be able to use this knowledge to your advantage if you require 
the best possible performance — traversing the UTF-16 view may be a bit faster than the 
UTF-8 or Unicode scalar views for non-ASCII data — but keep in mind that the 
in-memory format is an implementation detail that may change without notice. It’s 
possible that String will become more flexible in the future, e.g. by storing 
UTF-8-encoded text directly in UTF-8, thereby saving the effort of transcoding it to 
UTF-16. 

Strings received from Ob|ective-C are backed by an NSString. In this case, the NSString 
acts directly as the Swift string’s buffer to make the bridging efficient. An 
NSString-backed String will be converted to a native Swift string when it gets mutated. 


The Character Type 


The Internal structure of the Character type is interesting. As we’ve seen, Character 
represents a sequence of scalars that might be arbitrarily long. At the same time, 
grapheme clusters of arbitrary length are an edge case — the vast majority of characters 
are only a few bytes long. It’s a good idea to optimize for the common case by storing the 
bytes that make up the character in line as long as they don’t exceed a certain length, 
and only allocating a separate buffer for uncommonly large grapheme clusters. If you 
look at the source code, you’ll And that Character is essentially dehned like this: 

public struct Character { 
internal enum Representation { 
case smallUTF16(Builtin.lnt63) 
case large(Buffer) 

} 

internal var _representation: Representation 

} 

Character is a wrapper around an enum with two cases, .smallUTF16 and .large. The 
small case is used for grapheme clusters where the UTF-16 representation is 63 bits or 
less. (Builtin.lnt63 is an internal LLVM type that’s only available to the standard library.) 
The unusual size of 63 bits was carefully chosen to ht a Character instance into a single 
machine word. The remaining bit is needed to discriminate between the two enum 
cases. The compiler is smart enough to use so-called extra inhabitants — bit patterns 
that aren’t valid values for a particular type — in an enum’s associated values to store the 
enum case tag. This works here because the associated value for the large case (which is 
effectively a pointer) also has some spare bits. Pointer alignment rules mean that some 
bits of a valid object pointer will always be zero. 

Memory Layout<Character>.size //8 

This technique — holding a small number of elements internally and switching to a 
heap-based buffer — is sometimes called the “small string optimization.’’ It works 
particularly well here since the optimized case is so much more common than the 
unoptlmized one. 

String could proht from a similar optimization because many strings used in code are 
small enough to fit into an 8-byte word. Apple introduced such an optimization for 
NSString a few years ago, where short strings of up to 7 ASCII-only characters are stored 





d irectly in a tagged pointer, saving any extra heap allocations. (There’s even an extra 
mode with custom five- or six-bit encodings for strings of up to 11 characters out of a 
very constrained alphabet — it’s very clever.) Swift strings could get something like this 
in the future. Check out the Swift core team’s String Manifesto to learn more about the 
plans to provide additional performance enhancements for strings. 


A Simple Regular Expression Matcher 

To demonstrate some string processing techniques in the contex of a larger example, 
we’ll implement a simple regular expression matcher based on a similar matcher written 
in C in Brian W. Kernighan and Rob Pike’s The Practice of Programming. The original 
code, while beautifully compact, made extensive use of C pointers, so it often doesn’t 
translate well to other languages. But with Swift, through use of optionals and slicing, 
you can almost match the C version in simplicity. 

First, let’s define a basic regular expression type: 

///A simpie regular expression type, supporting'' and $ anchors, 

///and matching with . and * 

public struct Regex { 
private let regexp; String 

/// Construct from a regular expression String 
public init(_ regexp: String) { 
self.regexp = regexp 

} 

} 

Since this regular expression’s functionality is going to be so simple, it’s not really 
possible to create an “invalid” regular expression with its initializer. If the expression 
support were more complex (for example, supporting multi-character matching with []), 
you’d possibly want to give it a failable initializer. 

Next, we extend Regex to add a match function, which takes a string and returns true if it 
matches the expression: 

extension Regex { 

///Returns true if the string argument matches the expression. 
public func match(_ text: String) -> Bool { 




// If the regex starts with then it can only match the 
// start of the input 
if regexp.first 

return Regex.matchHere(regexp: regexp.dropFirstQ, 
text: text [...]) 

} 

// Otherwise, search for a match at every point in the input 
// until one is found 
var idx = text.startindex 

while true { 

if Regex.matchHere(regexp: regexp[...], 
text: text.suffix(from: idx)) 

{ 

return true 

} 

guard idx != text.endindex else { break} 
text.formlndex(after: &idx) 

} 

return false 

} 

} 

The matching function doesn’t do much except iterate over every possible substring of 
the input, from the start to the end, checking if it matches the regular expression from 
that point on. But if the regular expression starts with athen it need only match from 
the start of the text. 

matchHere is where most of the regular expression-processing logic lies: 
extension Regex { 

/// Match a regular expression string at the beginning of text. 
private static func matchHere( 
regexp: Substring, text: Substring) -> Bool 

{ 

// Empty regexprs match everything 
if regexp.isEmpty { 

return true 

} 


//Any character followed by * requires a call to matchStar 
if let c = regexp.first, regexp.dropFirstQ.first == "*" { 
return matchStar(character: c, regexp: regexp.dropFirst(2), text: text) 

} 

// if this is the last regex character and it's $, then it's a match iff the 
// remaining text is also empty 

if regexp.first == "$" && regexp.dropFirstQ.isEmpty { 
return text.isEmpty 

} 

// if one character matches, drop one from the input and the regex 
//and keep matching 

if let tc = text.first, let rc = regexp.first, rc == || to == rc { 

return matchHere(regexp: regexp.dropFirstQ, text: text.dropFirstQ) 

} 

// if none of the above, no match 

return false 

} 

///Search for zero or more 'c''s at beginning of text, followed by the 
/// remainder of the regular expression. 

private static func matchStar 

(character c: Character, regexp: Substring, text: Substring) -> Bool 

{ 

var idx = text.startindex 

while true { //a * matches zero or more instances 
if matchHere(regexp: regexp, text: text.suffix(from: idx)) { 

return true 

} 

if idx == text.endindex || (text[idx] != c && c != ''.'') { 

return false 

} 

text.formlndex(after: &idx) 

} 

} 

} 


The matcher is very simple to use: 


RegexC ''h..lo* !$''). match(" hellooooo true 


This code makes extensive use of slicing (both with range-based subscripts and with the 
dropFirst method) and optionals — especially the ability to equate an optional with a 
non-optional value. So, for example, if regexp.first == will work, even with an empty 

string, because '"'.first returns nil. However, you can still equate that to the non-optional 
and when it’s nil, it’ll return false. 

The ugliest part of the code is probably the while true loop. The requirement is that this 
loops over every possible substring, including an empty string at the end. This is to 
ensure that expressions like Regex("$").match("abc") return true. If strings worked 
similarly to arrays, with an integer index, we could write something like this: 

//... means up to_and including_ the endindex 
for idx in text.startindex...text.endindex { 

//Slice string between idx and the end 
if Regex.matchHere(regexp: _regexp, text: text[idx...]) { 

return true 

} 

} 

The hnal time around the for, idx would equal text.endIndex, so text[idx...] would be an 
empty string. 

So why doesn’t the for loop work? We mentioned in the built-in collection chapter that 
ranges are neither sequences nor collections by default. So we can’t iterate over a range 
of string indices because the range isn’t a sequence. And we can’t use the character 
view’s indices collection either, because it doesn’t include its endindex. As a result, we’re 
stuck with using the C-style while loop. 


ExpressibleByStringLiteral 

Throughout this chapter, we’ve been using StringC'blah") and "blah" pretty much 
interchangeably, but they’re different. "" is a string literal, just like the array literals 
covered in the collection protocols chapter. You can make your types initlalizable from a 
string literal by conforming to ExpressibleByStringLiteral. 

String literals are slightly more complicated than array literals because they’re part of a 
hierarchy of three protocols: ExpressibleByStringLiteral, 


ExpressibleByExtendedGraphemeClusterLiteral, and Expressible By UnicodeScalarLiteral. 
Each defines an in it for creating a type from each kind of iiterai, but unless you really 
need fine-grained logic based on whether or not the value is being created from a single 
scalar/cluster, you only need to implement the string version; the others are covered by 
default implementations that refer to the string literal initializer: 

extension Regex: ExpressibleByStringLiteral { 
public init(stringLiteral value: String) { 
regexp = value 

} 

} 

Once defined, you can begin using string literals to create the regex matcher by explicitly 
naming the type: 

let r: Regex = ''''h..lo*!$'' 

Or even better is when the type is already named for you, because the compiler can then 
infer it: 

func findMatches(in strings: [String], regex: Regex) -> [String] { 
return strings.filter {regex.match($0)} 

} 

findMatches(in: ["foo'',"bar",''baz"], regex: "''b..") //["bar", "baz"] 

CustomStringConvertible and 
CustomDebugStringConvertible 

Functions like print, String(describing:), and string interpolation are written to take any 
type, no matter what. Even without any customization, the results you get back might be 
acceptable because structs print their properties by default: 

print(Regex("colou?r'')) 

//prints out Regex(regexp: "colou?r") 

Then again, you might want something a little prettier, especially if your type contains 
private variables you don’t want displayed. But never fear! It only takes a minute to give 
your custom class a nicely formatted output when it’s passed to print: 


extension Regex: CustomStringConvertible { 
public var description: String { 
return ''/\(regexp)/'' 

} 


Now, if someone converts your custom type to a string through various means — using it 
with a streaming function iike print, passing it to String(describing:), or using it in some 
string interpolation — it’ll print out as /expression/: 

let regex = Regex("colou?r'') 
print(regex) // /colou?r/ 

There’s also CustomDebugStringConvertible, which you can implement when someone 
calls String(reflecting:), in order to provide more debugging output than the 
pretty-printed version: 

extension Regex: CustomDebugStringConvertible { 
public var debugDescription: String { 
return ''{expression: \(regexp)}" 

} 


String(reflecting:) falls back to using CustomStringConvertible if 
CustomDebugStringConvertible isn’t implemented, and vice versa. So often, 
CustomDebugStringConvertible isn’t worth implementing if your type is simple. 
However, if your custom type is a container, it’s probably polite to conform to 
CustomDebugStringConvertible in order to print the debug versions of the elements the 
type contains. So we can extend the FIFOQueue example from the collection protocols 
chapter: 

extension FIFOQueue:CustomStringConvertible, 

CustomDebugStringConvertible 

{ 

public var description: String { 

// Print contained elements using String(describing:), which favors 
// CustomStringConvertible 

let elements = map {String(describing: $0) }.joined(separator: ", ") 
return "[\(elements)]" 

} 


public var debugDescription: String { 

// Print contained elements using String(reflecting:), which favors 
// CustomDebugStringConvertible 

let elements = map {String(reflecting: $0) }.joined(separator: ", ") 
return "FIFOQueue: [\(elements)]" 

} 

} 

Note the word “favors” in the comments there — String(describing:) falls back to 
CustomDebugStringConvertible if CustomStringConvertible isn’t available — so if you do 
anything out of the ordinary when printing for debug, be sure to implement 
CustomStringConvertible as well. But if your implementations for description and 
debugDescription are identical, you can pick either one and omit the other. 

By the way. Array always prints out the debug description of its elements, even when 
invoked via String(describing:). The reason given on the swlft-dev mailing list was that 
an array’s description should never be presented to the user, so debugging is the only 
use case. And an array of empty strings would look wrong without the enclosing quotes, 
which String.description omits. 

Given that conforming to CustomStringConvertible implies that a type has a pretty print 
output, you may be tempted to write something like the following generic function: 

func doSomethingAttractive<T: CustomStringConvertible>(with value:!) { 

// Print out something incorporating value, safe in the knowledge 
// it will print out sensibly. 

} 

But you’re not supposed to use CustomStringConvertible in this manner. Instead of 
poking at types to establish whether or not they have a description property, you should 
use String(describing:) regardless and live with the ugly output if a type doesn’t conform 
to the protocol. This will never fail for any type. And it’s a good reason to implement 
CustomStringConvertible whenever you write more than a very simple type. It only takes 
a handful of lines. 


Text Output Streams 


The print and dump functions in the standard library log text to the standard output. 
How does that work? The default versions of these functions forward to overloads 



named print(_:to:) and dump(_:to:). The to: argument is the output target; it can be any 
type that conforms to the TextOutputStream protocoi: 

public func print<Target:TextOutputStream> 

(_ items: Any..., separator: String = '' ", 
terminator: String = ''\n", to output: inout Target) 

The standard library maintains an internal text output stream that writes everything 
that’s streamed to it to the standard output. What else can you write to? Well, String is 
the only type in the standard library that’s an output stream: 


var s = 

let numbers = [1,2,3,4] 
print(numbers, to: &s) 
s//[l,2, 3,4] 

This is useful if you want to reroute the output of the print and dump functions into a 
string. Incidentally, the standard library also harnesses output streams to allow Xcode to 
capture all stdout logging. Take a look at this global variable declaration in the standard 
li brary: 

public var _playgroundPrintHook: ((String) -> Void)? 

If this is non-nil, print will use a special output stream that routes everything that’s 
printed both to the standard output and to this function. The declaration is even public, 
so you can use this for your own shenanigans: 

var printCapture = 

_playgroundPrintHook = {text in 
printCapture -l-= text 

} 

printC'This is supposed to only go to stdout") 
printCapture//Th/s is supposed to only go to stdout 

But don’t rely on it! It’s totally undocumented, and we don’t know what functionality in 
Xcode will break when you reassign this. 

We can also make our own output streams. The protocol has only one requirement: a 
write method that takes a string and writes it to the stream. For example, this output 
stream buffers writes to an array: 



struct ArrayStream:TextOutputStream { 
var buffer: [String] = [] 
mutatingfunc writeL string: String) { 
buffer.append(string) 

} 

} 

var stream = ArrayStreamQ 

printC'Helto'', to: &stream) 

printC'World'', to: Scstream) 

stream.buffer/^/""" "Hello", "\n", "World", "\n"] 

The documentation explicitly allows functions that write to an output stream to call 
write(_:) multiple times per writing operation. That’s why the array buffer in the example 
above contains separate elements for line breaks and even some empty strings. This is 
an implementation detail of the print function that may change in future releases. 

Another possibility is to extend Data so that it takes a stream, writing it as 
UTF-8-encoded output: 

extension Data:TextOutputStream { 
mutating public func writeL string: String) { 
self.append(contentsOf: string.utfS) 

} 

} 

var utfSData = DataQ 
var string = "cafe” 
utf8Data.write(string) /'O 

The source of an output stream can be any type that conforms to the 
TextOutputStreamable protocol. This protocol requires a generic method, write(to:), 
which accepts any type that conforms to TextOutputStream and writes self to it. 

In the standard library. String, Substring, Character, and Unicode.Scalar conform to 
TextOutputStreamable, but you can also add conformance to your own types. One way to 
do this is with print(_:to:). However, it’s very easy to make a mistake here by accidentally 
forgetting the to: parameter. Unless you test with a target that’s not the standard output, 
you might not even notice the oversight. Another option is to call the target stream’s 
write method directly. This is how the queue type we built in the chapter on collection 
protocols could adopt TextOutputStreamable: 


extension FIFOQueueiTextOutputStreamable { 
func write<Target:TextOutputStream>(to target: inout Target) { 
target.write("['') 

target.write(map {String(describing: $0) }.joined(separator: 
target.writeC']") 

} 

} 

var textRepresentation = 
let queue: FIFOQueue = [1,2,3] 
queue.write(to: &textRepresentation) 
textRepresentation /7 [1,2,3] 

This isn’t very different from saying let textRepresentation = String(describing: queue) 
though, aside from being more complicated. One interesting aspect of output streams 
that a source can call write multiple times and the stream will process each write 
immediately. You can see this if you write the following rather silly sample: 

struct SlowStreamer:TextOutputStreamable, ExpressibleByArrayLiteral { 
let contents: [String] 

init(arrayLiteral elements: String...) { 
contents = elements 

} 

func write<Target:TextOutputStream>(to target: inout Target) { 
for X in contents { 
target.write(x) 
target.write("\n'') 
sleep(l) 

} 

} 

} 

let slow: SlowStreamer = [ 

''You'll see that this gets", 

"written slowly line by line", 

"to the standard output", 

] 

print(slow) 


As new lines are printed to target, the output appears; it doesn’t wait for the call to 
complete. 

As we’ve seen, internally, print is using some TextOutputStream-conforming wrapper on 
the standard output. You could write something similar for standard error, like this: 

struct StdErriTextOutputStream { 
mutatingfunc writeL string: String) { 
guard istring.isEmpty else { return } 

//Strings can be passed directly into C functions that take a 
// const char* - see the interoperability chapter for more! 
fputs(string, stderr) 

} 


var standarderror = StdErrO 
printC'oops!", to: Sstandarderror) 

Streams can also hold state, they can potentially transform their output, and you can 
chain them together. The following output stream replaces all occurrences of the 
specified phrases with the given alternatives. Like String, it also conforms to 
TextOutputStreamabie, making it both a target and a source of text-streaming 
operations: 

struct RepiacingStream:TextOutputStream,TextOutputStreamabie { 
let toReplace: DictionaryLiterakString, String> 
private var output = 

init(repiacing toReplace: DictionaryLiterakString, String>) { 
self.toRepiace = toReplace 

} 

mutating func writeL string: String) { 
let toWrite = toReplace.reduce(string) { partialResult, pair in 
partialResuit.repiacingOccurrences(of: pair.key, with: pair.vaiue) 

} 

print(toWrite, terminator:to: Stoutput) 

} 


func write<Target:TextOutputStream>(to target: incut Target) { 


output.write(to: Sctarget) 

} 

} 

var replacer = ReplacingStream(replacing: [ 

"in the cloud": "on someone else's computer" 

]) 

let source = "People find it convenient to store their data in the cloud." 
print(source, terminator:to: Sreplacer) 

var output = "" 

print(replacer, terminator:to: Soutput) 
output 

//People find it convenient to store their data on someone else's computer. 

DictionaryLiteral is used in the above code instead of a regular dictionary. This is useful 
when you want to be able to use the [key: value] literal syntax, but you don’t want the two 
side effects you’d get from using a Dictionary: elimination of duplicate keys and 
reordering of the keys. If this indeed isn’t what you want, then DictionaryLiteral is a nice 
alternative to an array of pairs (l.e. [(key, value)]) while allowing the caller to use the 
more convenient [:] syntax. 


String Performance 

There’s no denying that coalescing multiple variable-length UTF-16 values into 
extended grapheme clusters is going to be more expensive than just ripping through a 
buffer of 16-bit values. But what’s the cost? One way to test performance would be to 
adapt the regular expression matcher above to work against all of the different string 
views. 

However, this presents a problem. Ideally, you’d write a generic regex matcher with a 
placeholder for the view. But this doesn’t work — String and its views don’t all 
implement a common “string view’’ protocol. Also, in our regex matcher, we need to 
represent specific character constants like * and * to compare against the regex. In the 
UTF16View, these would need to be UInti 6, but with the string itself, they’d need to be 
Character. Finally, we want the regex matcher Initializer itself to still take a String. How 
would it know which method to call to get the appropriate view out? 


One technique is to bundle up all the variable logic into a single type and then 
parameterize the regex matcher on that type. First, we define a protocol that has all the 
necessary information: 

protocol StringViewSelector { 
associatedtype View: Collection 

static var caret: View.Element { get } 
static var asterisk: View.Element { get} 
static var period: View.Element { get } 
static var dollar: View.Element { get } 

static func viewffrom s: String) -> View 

} 

This information includes an associated type for the view we’re going to use, getters for 
the four constants needed, and a function to extract the relevant view from a string. 

Given this, you can impiement concrete versions like so: 

struct UTFSViewSelector: StringViewSelector { 
static var caret: UIntS { return Ulnt8(ascii:} 
static var asterisk: UIntS { return Ulnt8(ascii: } 

static var period: Ulnt8 { return Ulnt8(ascii:} 
static var dollar: Ulnt8 { return Ulnt8(ascii: "$") } 

static func view(from s: String) -> String.UTF8View { return s.utf8} 

} 

struct CharacterViewSelector: StringViewSelector { 
static var caret: Character { return } 
static var asterisk: Character { return } 
static var period: Character { return } 
static var dollar: Character { return } 

static func viewffrom s: String) -> String { return s} 

} 

You can probably guess what UTF1 BViewSelector and UnicodeScalarViewSelector look 
like. 


These are what some people call “phantom types” — types that only exist at compile 
time and don’t actually hold any data. Try calling 

MemoryLayout<CharacterViewSelector>.size — it’ll return zero because it contains no 
data. All we’re using these types for is to parameterize behavior of another type: the 
regex matcher. It’ll use them like so: 

struct Regex<V: StringViewSelector> 
where V.View.Element: Equatable, 

V.View.SubSequence: Collection 

{ 

let regexp: String 

/// Construct from a regular expression String. 
init(_ regexp: String) { 
self.regexp = regexp 

} 

} 

extension Regex { 

///Returns true if the string argument matches the expression. 
func matchL text: String) -> Bool { 
let text = V.view(from: text) 
let regexp = V.view(from: self.regexp) 

// if the regex starts with then it can only match the start 

//of the input. 

if regexp.first == V.caret { 

return Regex.matchHere(regexp: regexp.dropFirstQ, text: text[...]) 

} 

// Otherwise, search for a match at every point in the input until 

//one is found. 

var idx = text.startindex 

while true { 

if Regex.matchHere(regexp: regexp[...], text: text.suffix(from: idx)) { 

return true 

} 

guard idx != text.endindex else { break} 
text.formlndex(after: &idx) 

} 

return false 

} 


/// Match a regular expression string at the beginning of text. 
private static func matchHere( 

regexp: V.View.SubSequence, text: V.View.Subsequence) -> Bool 

{ 

} 


Once the code is rewritten iike this, we can write some benchmarking code that 
measures the time taken to process some arbitrary reguiar expression across a very iarge 
input: 

func benchmark<V: StringViewSelector>(_: V.Type, pattern: String, text: String) 

-> Timeinterval 

where V.View.Element: Equatable, V.View.SubSequence: Collection 

{ 

let r = Regex<V>(pattern) 

let lines = text.split(separator: ''\n'').map(String.init) 
var count = 0 

let startTime = CFAbsoluteTimeGetCurrentQ 
for line in lines { 

if r.match(line) {count = count &+ 1 } 

} 

let totalTime = CFAbsoluteTimeGetCurrentO - startTime 
return totalTime 

} 

let timeCharacter = benchmark(CharacterViewSelector.self, 
pattern: pattern, text: input) 

let timeUnicodeScalar = benchmark(UnicodeScalarViewSelector.self, 
pattern: pattern, text: input) 
lettimeUTF16 = benchmark(UTF8ViewSelector.self, 
pattern: pattern, text: input) 
lettimeUTFS = benchmark(UTF16ViewSelector.self, 
let pattern: pattern, text: input) 


The results show the following speeds for the different views in processing the regex on a 
large corpus of English (128,000 lines, 6.5 million characters) and Chinese (43,000 lines, 
1.5 million characters) text: 


View_ASCII text 

Characters 1.4 seconds 

Unicode.Scalars 1.6 seconds 

UTF-16 0.7 seconds 

UTF-8 1.1 seconds 


Chinese text 

3.5 seconds 
1.1 seconds 
0.5 seconds 
n/a 


(Benchmarking the UTF-8 view for Chinese text doesn’t make sense because it can 
deliver incorrect results.) 

As you can see, the UTF-16 view is consistently the fastest in this test. But how much 
faster it is depends on the input. It’s also worth noting that processing of Characters got 
much faster in Swift 4.0. When we ran the ASCII benchmark with Swift 3.0 for the 
previous edition of this book, the character view was more than 10 times slower than any 
of the other three. The penalty for Unicode correctness is no longer as hig in Swift 4.0. 

Only you can know if your use case justifies choosing your view type based on 
performance. It’s almost certainly the case that these performance characteristics only 
matter when you’re doing extremely heavy string manipulation, but if you’re certain that 
what you’re doing would be correct when operating on UTF-16, Unicode scalar, or UTF-8 
data, this can still give you a decent speedup. 


Recap 

Strings in Swift are very different than their counterparts in almost all other mainstream 
programming languages. When you’re used to strings effectively being arrays of code 
units, it’ll take a while to switch your mindset to Swift’s approach of prioritizing Unicode 
correctness over simplicity. 

Ultimately, we think Swift makes the right choice. Unicode text is much more 
complicated than what those other languages pretend it is. In the long run, the time 
savings from avoided bugs you’d otherwise have written will probably outweigh the time 
it takes to unlearn integer indexing. 




We’re so used to random “character” access that we may not realize how rarely this 
feature is really needed in string processing code. We hope the examples in this chapter 
convince you that simple in-order traversal is perfectly fine for most common 
operations. Forcing you to be explicit about which representation of a string you want to 
work on — grapheme clusters, Unicode scalars, UTF-16 or UTF-8 code units — is another 
safety measure; readers of your code will be grateful for it. 

When Chris Lattner outlined the goals for Swift’s string implementation in July 2016, he 
ended with this: 


Our goal is to be better at string processing than Perl! 


Swift 4 isn’t quite there yet — too many desirable features are missing, including moving 
more string APIs from Foundation into the standard library, native language support for 
regular expressions, string formatting and parsing APIs, and more powerful string 
interpolation. The good news it that the Swift team has expressed interest in tackling all 
t hese topics in the future. 





Error Handling 




Swift provides muitiple ways for deaiing with errors and even ailows us to build our own 
mechanisms. In the chapter on optionals, we looked at two of them: optionals and 
assertions. An optional indicates that a value may or may not be there; we have to 
inspect the optional and unwrap the value before we can use it. An assertion validates 
that a condition is true; if the condition doesn’t hold, the program crashes. 

Looking at the interfaces of types in the standard library can give us a good feel for when 
to use an optional and when not to. Optionals are used for operations that have a clear 
and commonly used “not found” or “Invalid input” case. For instance, consider the 
failable initializer for I nt that takes a string; it returns nil if the input isn’t a valid integer. 
Another example: when you look up a key in a dictionary, it’s often expected that the key 
might not be present. Therefore, a dictionary lookup returns an optional result. 

Contrast this with arrays: when looking up an element at a specihc index, the element is 
returned directly and isn’t wrapped in an optional. This is because the programmer is 
expected to know if an array index is valid. Accessing an array with an index that’s out of 
bounds is considered a programmer error, and consequently, this will crash your 
application. If you’re unsure whether or not an index is within bounds, you need to 
check beforehand. 

Assertions are a great tool for identifying bugs in your code. Used correctly, they show 
you at the earliest possible moment when your program is in a state you didn’t expect. 
They should never be used to signal expected errors such as a network error. 

Note that arrays also have accessors that return optionals. For example, the first and last 
properties on Collection return nil when called on an empty collection. The developers 
of Swift’s standard library deliberately designed the API this way because it’s common to 
access these values in situations when the collection might be empty. 

An alternative to returning an optional from a function that can fall is to mark the 
function as throws. Besides a different syntax for how the caller must handle the success 
and failure cases, the key difference to returning an optional is that throwing functions 
can return a rich error value that carries Information about the error that occurred. 

This difference is a good guideline for when to use one approach over the other. 

Consider the first and last properties on Collection again. They have exactly one error 
condition (the collection is empty) — returning a rich error wouldn’t give the caller more 
information than what’s already present in the optional value. Compare this to a 
function that executes a network request: many things can fail, from the network being 
down, to being unable to parse the server’s response. Rich error information is 



necessary to allow the caller to react differently to different errors (or just to show the 
user what exactly went wrong). 


The Result Type 

Before we look at Swift’s huilt-in error handling in more detail, let’s discuss the Result 
type, which will help clarify how Swift’s error handling works when you take away the 
syntactic sugar. A Result type is very similar to an optional. Recall that an optional is 
just an enumeration with two cases: a .none or nil case, with no associated value; and a 
.some case, which has an associated value. The Result type is an enum with two cases as 
well: a failure case, which carries an associated error value; and a success case, also with 
an associated value. Just like optionals. Result has one generic parameter; 

enum Result<A> { 
case failure(Error) 
case success(A) 

} 

The failure case constrains its associated value to the Error protocol. We’ll come back to 
this shortly. 

Let’s suppose we’re writing a function to read a file from disk. As a hrst try, we could 
dehne the interface using an optional. Because reading a file might fail, we want to be 
able to return nil: 

func contentsOrNil(ofFile filename: String) -> String? 

The Interface above is very simple, but it doesn’t tell us anything about why reading the 
hie failed. Does the file not exist? Or do we not have the right permissions? This is 
another example where the failure reason matters. Let’s define an enum for the possible 
error cases: 

enum FileError: Error { 
case fileDoesNotExist 
case noPermission 

} 

Now we can change the type of our function to return either an error or a valid result: 


func contents(ofFile filename: String) -> Result<String> 


The caller of the function can look at the result cases and react differently based on the 
error. In the code below, we try to read the file, and in case reading succeeds, we print 
the contents. If the hie doesn’t exist, we print that, and we handle any remaining errors 
in a different way: 

let result = contentsfofFile: "input.txt") 

switch result { 

case let .success(contents): 

print(contents) 
case let .failure(error): 
if let fileError = error as? FileError, 
fileError == .fileDoesNotExist 

{ 

printC'File not found") 

} else { 

// Handle error 

} 

} 


Throwing and Catching 

Swift’s built-in error handling is implemented almost like in the above example, only 
with a different syntax. Instead of giving a function a Result return type to indicate that 
it can fail, we mark it as throws. Note that Result applies to types, whereas throws 
applies to functions (we’ll come back to this difference later in this chapter). For every 
throwing function, the compiler will verify that the caller either catches the error or 
propagates it to its caller. In the case of contents(ofFile:), the function signature 
including throws looks like this: 

func contents(ofFile filename: String) throws -> String 

From now on, our code won’t compile unless we annotate every call to contents(ofFile:) 
with try. The try keyword serves two purposes: hrst, it signals to the compiler that we 
know we’re calling a function that can throw an error. Second, and more importantly, it 
immediately makes clear to readers of the code which functions can throw. 


Calling a throwing function also forces us to make a decision about how we want to deal 
with possible errors. We can either handle an error by using do/catch, or we can have it 
propagate up the call stack by marking the calling function as throws. We can use 
pattern matching to catch specific errors or catch all errors. In the example below, we 
explicitly catch a fileDoesNotExist case and then handle all other errors in a catch-all 
case. Within the catch-all case, the compiler automatically makes a variable, error, 
available (much like the implicit newValue variable in a property’s willSet handler): 

do { 

let result = try contents(ofFile: "input.txt") 
print(resu[t) 

} catch FileError.fileDoesNotExist { 
printC'File not found") 

} catch { 
print(error) 

// Handle any other error 

} 


The error handling syntax in Swift probably looks familiar to you. Many other 
languages use the same try, catch, and throw keywords for exception handling. 
Despite the resemblance, error handling in Swift doesn’t incur the runtime 
cost that’s often associated with exceptions. The compiler treats throw like a 
regular return, making both code paths very fast. 


If we want to expose more information in our errors, we can use an enum with 
associated values. For example, a file parser could choose to model the possible errors 
like this: 

enum ParseError: Error { 
case wrongEncoding 
case warning(line: Int, message: String) 

} 

Note that we could’ve also used a struct or class instead; any type that conforms to the 
Error protocol can be used as an error in a throwing function. And because the Error 
protocol has no requirements, any type can choose to conform to it without extra 
implementation work. 



Now, if we want to parse a string, we can again use pattern matching to distinguish 
between the cases. In the case of. warni ng, we can bind the iine number and warning 
message to a variable: 

do { 

let result = try parse(text: "{\''message\": \''We come in peace\" }") 
print(result) 

} catch ParseError.wrongEncoding { 
printC'Wrong encoding") 

} catch let ParseError.warning(line, message) { 
printC Warning at line \(line):\(message)") 

} catch { 

} 

Something about the above code doesn’t feel quite right. Even if we’re absolutely sure 
that the only error that could happen is of type ParseError (which we handled 
exhaustively), we still need to write a final catch case to convince the compiler that we 
caught all possible errors. In a future Swift version, the compiler might be able to check 
exhaustiveness within a module, but across modules, this problem can’t be solved. The 
reason is that Swift errors are untyped: we can only mark a function as throws, but we 
can’t specify which errors it’ll throw. This was a deliberate design decision — most of the 
time, you only care about whether or not an error was present. If we needed to specify 
the types of all errors, this could quickly get out of hand: it would make functions’ type 
signatures quite complicated, especially for functions that call several other throwing 
functions and propagate their errors. Moreover, adding a new error case would be a 
breaking change for all clients of the API. 

That said. Swift might get typed errors someday; this topic is being actively discussed on 
the mailing lists. If typed errors come to Swift, we expect them to be an opt-in feature 
because untyped errors are still the better choice in many situations. For example, 
frameworks like Cocoa probably won’t ever have typed errors . 


Because errors are untyped, it’s important to document the types of errors your 
functions can throw. Xcode supports a Throws keyword in documentation 
markup for this purpose. Here’s an example: 

/// Opens a text file and returns its contents. 

/// 

/// - Parameter filename: The name of the file to read. 

/// - Returns: The file contents, interpreted as UTF-8. 





/// - Throws: 'FileError' if the file does not exist or 
/// the process doesn't have read permissions. 
func contents(ofFile filename: String) throws -> String 


The Quick Help popover that appears when you Option-click on the function 
name will now include an extra section for the thrown errors. 


Typed Errors 

It can sometimes be useful to take advantage of the type system to specify the concrete 
errors a function can throw. We can come up with a slightly altered Result type, which 
has an additional generic parameter for the error type: 

enum Result<A, ErrorType: Error> { 
case failure(ErrorType) 
case success(A) 

} 

This way, we can declare functions using an explicit error type. The following parseFile 
function will return either an array of strings or a ParseError. We don’t have to handle 
any other cases when calling it, and the compiler knows this: 

func parse(text: String) -> Result<[String], ParseError> 

In code where your errors have a significant semantic meaning, you can choose to use a 
typed Result type instead of Swift’s built-in error handling. This way, you can let the 
compiler verify that you caught all possible errors. However, in most applications, using 
throws and do/try/catch will lead to simpler code. There’s another big benefit to using 
the built-in error handling: the compiler will make sure you can’t ignore the error case 
when calling a function that might throw. With the definition of parseFile above, we 
could write the following code: 

_ = parse(text: invalidData) 

If the function were marked as throws, the compiler would force us to call it using try. 
The compiler would also force us to either wrap that call in a do/catch block or propagate 
the error. 



Granted, the example above is unrealistic, because ignoring the parse function’s return 
value doesn’t make any sense, and the compiler would force you to consider the failure 
case when you unwrap the result. It’s relevant when dealing with functions that don’t 
have a meaningful return value, though, and in these situations, it can really help you 
not forget to catch the error. For example, consider the following function: 

func setupServerConnectionO throws 

Because the function is marked as throws, we need to call it with try. If the server 
connection fails, we probably want to switch to a different code path or display an error. 
By having to use try, we’re forced to think about this case. Had we chosen to return a 
Resuit<()> instead, it would be all too easy to ignore errors. 


Bridging Errors to Objective-C 

Objective-C has no mechanism that’s similar to throws and try. (Objective-C does have 
exception handling that uses these same keywords, but exceptions in Objective-C should 
only be used to signal programmer errors. You rarely catch an Objective-C exception in a 
normal app.) 

Instead, the common pattern in Cocoa is that a method returns NO or nil when an error 
occurs. In addition, failable methods take a reference to an NSError pointer as an extra 
argument; they can use this pointer to pass concrete error information to the caller. For 
example, the contents(ofFile:) method would look like this in Objective-C: 

- (NSString *)contentsOfFile(NSString *)fiiename error:(NSError **)error; 

Swift automatically translates methods that follow this pattern to the throws syntax. The 
error parameter gets removed since it’s no longer needed, and BOOL return types are 
changed to Void. This is helpful when dealing with existing frameworks in Objective-C. 
The method above gets imported like this: 

func contents(ofFile filename; String) throws -> String 

Other NSError parameters — for example, in asynchronous APIs that pass an error back 
to the caller in a completion block — are bridged to the Error protocol, so you don’t 
generally need to interact with NSError directly. 


If you pass a pure Swift error to an Objective-C method, it’ll be bridged to NSError. Since 
all NSError objects must have a domain string and an integer error code, the runtime will 
generate default values, using the qualified type name as the domain and numbering the 
enum cases from zero for the error code. Optionally, you can provide your own values by 
conforming your type to the Custom NSError protocol. 

For example, we could extend our ParseError like this: 

extension ParseError: CustomNSError { 
static let errorDomain = "io.objc.parseError" 
var errorCode: Int { 
switch self { 

case .wrongEncoding: return 100 
case .warningL, _): return 200 
} 

} 

var errorUserInfo: [String: Any] { 
return [:] 

} 

} 

In a similar manner, you can add conformance to one or both of the following protocols 
to make your errors more meaningful and provide better interoperability with Cocoa 
conventions: 

^ LocalizedError — provides localized messages describing why the error occurred 
(failureReason), tips for how to recover (recoverySuggestion), and additional help 
text (helpAnchor). 

-> RecoverableError — describes an error the user can recover from by presenting 
one or more recoveryOptions and performing the recovery when the user requests 
it. 


Even without conforming to LocalizedError, every type that conforms to Error 
has a localized Description property. Any type conforming to Error can also 
define a custom localizedDescription. However, as it’s not a requirement of the 
Error protocol, the property isn’t dynamically dispatched. Unless you also 
conform to LocalizedError, your custom localizedDescription won’t be used by 
Objectlve-C APIs or if you’re inside an Error existential container. See the 



protocols chapter for more information on dynamic dispatch and existential 
containers. 


Errors and Function Parameters 


In the following example, we’ll write a function that checks a list of flies for validity. The 
checkFiie function can return three possible values. If It returns true, the file is valid. If it 
returns false, the file is invalid. If it throws an error, something went wrong when 
checking the file: 

func checkFiie(filename: String) throws -> Bool 

As a first step, we can write a simple function that loops over a list of filenames and 
makes sure that checkFiie returns true for every file. If checkFiie returns false, we want 
to make sure to exit early, avoiding any unnecessary work. Since we don’t catch any 
errors that checkFiie throws, the first error would propagate to the caller and thus also 
exit early: 

func checkAllFilesffilenames: [String]) throws -> Bool { 
for filename in filenames { 

guard try oheckFileffilename: filename) else { return false } 

} 

return true 

} 

Checking whether all the elements in an array conform to a certain condition is 
something that might happen more often in our app. For example, consider the function 
checkPrimes, which checks whether all numbers in a given list are prime numbers. It 
works in exactly the same way as checkAllFiles. It loops over the array and checks all 
elements for a condition (isPrime), exiting early when one of the numbers doesn’t satisfy 
the condition: 

func checkPrimesL numbers: [Int]) -> Bool { 
for number in numbers { 
guard number.isPrime else { return false } 

} 

return true 


} 


checkPrimes([2,3,7,17]) true 
checkPrimes([2,3,4,5]) /7fa/se 

Both functions mix the process of iterating over a sequence (the for loops) with the 
actual logic that decides if an element meets the condition. This is a good opportunity to 
create an abstraction for this pattern, similar to map or filter. To do that, we can add a 
function named aU(matching:) to Sequence. Like filter, all takes a function that performs 
the condition check as an argument. The difference to filter is the return type, all returns 
true if all elements in the sequence satisfy the condition, whereas filter returns the 
elements themselves: 

extension Sequence { 

///Returns 'true'iff alt elements satisfy the predicate 
func all(matching predicate: (Element) -> Bool) -> Bool { 
for element in self { 

guard predicate(element) else { return false } 

} 

return true 

} 


This allows us to rewrite checkPrimes in a single line, which makes it easier to read once 
you know what all does, and it helps us focus on the essential parts: 

func checkPrimes2(_ numbers: [Int]) -> Bool { 
return numbers.all {$0.isPrime} 

} 

However, we can’t rewrite checkAllFiles to use all, because checkFile is marked as throws. 
We could easily rewrite all to accept a throwing function, but then we’d have to change 
checkPrimes too, either by annotating checkPrimes as throwing, by using try!, or by 
wrapping the call to all in a do/catch block. Alternatively, we could define two versions 
of all: one that throws and one that doesn’t. Except for the try call, their 
implementations would be identical. 


Rethrows 

Fortunately, there’s a better way. By marking all as rethrows, we can write both variants 
in one go. Annotating a function with rethrows tells the compiler that this function will 


only throw an error when its function parameter throws an error. This aliows the 
compiler to waive the requirement that all must he called with try when the caller passes 
in a non-throwing check function: 

extension Sequence { 

func all(matching predicate: (Element) throws -> Bool) rethrows 
-> Bool { 

for element in self { 

guard try predicate(element) else { return false } 

} 

return true 

} 


The implementation of checkAllFiles is now very similar to checkPrimes, but because 
the call to all can now throw an error, we need to insert an additional try: 

func checkAllFiles(filenames: [String]) throws -> Bool { 
return try filenames.all(matching: checkFile) 

} 

Almost all sequence and collection functions in the standard library that take a function 
argument are annotated with rethrows. For example, the map function is only throwing 
if the transformation function is a throwing function itself 


Cleaning Up Using defer 

Let’s go back to the contents(ofFile:) function from the beginning of this chapter for a 
minute and have a look at the implementation. In many languages, it’s common to have 
a try/finally construct, where the block marked with finally is always executed when the 
function returns, regardless of whether or not an error was thrown. The defer keyword 
in Swift has a similar purpose but works a bit differently. Like finally, a defer block is 
always executed when a scope is exited, regardless of the reason of exiting — whether it’s 
because a value is successfully returned, because an error happened, or any other 
reason. Unlike finally, a defer block doesn’t require a leading try or do block, and it’s 
more flexible in terms of where you place it in your code: 

func contents(ofFile filename: String) throws -> String 

{ 

let file = openC'test.txt", 0_RD0NLY) 


defer {close(file)} 

let contents = try process(file: file) 

return contents 

} 

While defer is often used together with error handling, it can be useful in other contexts 
too — for example, when you want to keep the code for initialization and cleanup of a 
resource close together. Putting related parts of the code close to each other can make 
your code significantly more readable, especially in longer functions. 

If there are multiple defer blocks in the same scope, they’re executed in reverse order; 
you can think of them as a stack. At first, it might feel strange that the defer blocks run 
in reverse order. However, if we look at an example, it should quickly make sense: 

guard let database = openDatabasef...) else { return } 
defer {closeDatabase(database)} 

guard let connection = openConnection(database) else { return } 

defer {closeConnection(connection)} 

guard let result = runQueryfconnection,...) else { return } 

If an error occurs — for example, during the runQuery call — we want to close the 
connection first and the database second. Because the defer is executed in reverse order, 
this happens automatically. The runQuery depends on openConnection, which in turn 
depends on openDatabase. Therefore, cleaning these resources up needs to happen in 
reverse order. 

There are some situations in which defer blocks don’t get executed: when your program 
segfaults, or when it raises a fatal error (e.g. using fatalError or by force-unwrapping a 
nil), all execution halts immediately. 


Errors and Optionals 

Errors and optionals are both very common ways for functions to signal that something 
went wrong. Earlier in this chapter, we gave you some advice on how to decide which 
pattern you should use for your own functions. You’ll end up working a lot with both 
errors and optionals, and passing results to other APIs will often make it necessary to 
convert back and forth between throwing functions and optional values. 


The try? keyword allows us to ignore the error of a throws function and convert the 
return value into an optional that tells us if the function succeeded or not: 

if let result = try? parse(text: input) { 
print(resuit) 

} 

Using the try? keyword means we receive less information than before: we only know if 
the function returned a successful value or if it returned some error — any specihc 
information about that error gets thrown away. To go the other way, from an optional to 
a function that throws, we have to provide the error value that gets used in case the 
optional is nil. Here’s an extension on Optional that, given an error, does this: 

extension Optional { 

/// Unwraps 'self if it is non-'nif. 

/// Throws the given error if 'self is 'nil'. 
func or(error: Error) throws -> Wrapped { 
switch self { 
case let x?: return x 
case nil: throw error 

} 

} 

} 

do { 

let int = try lnt("42").or(error: ReadIntError.couldNotRead) 

} catch { 
print(error) 

} 

This can he useful in conjunction with multiple try statements, or when you’re working 
inside a function that’s already marked as throws. 

The existence of the try? keyword may appear contradictory to Swift’s philosophy that 
ignoring errors shouldn’t be allowed. However, you still have to explicitly write try? so 
that the compiler forces you to acknowledge your actions. In cases where you’re not 
interested in the error message, this can be very helpful. 

It’s also possible to write equivalent functions for converting between Result and throws, 
or between throws and Result, or between optionals and Result. 


There’s a third variant of try: try!. This is used when you know there can’t possibly he an 
error resuit. Just iike force-unwrapping an optionai value that’s nil, try! crashes when 
the result was actually an error. 


Chaining Errors 

Chaining multiple calls to functions that can throw errors becomes trivial with Swift’s 
built-in error handling — there’s no need for nested if statements or similar constructs; 
we simply place these calls into a single do/catch block (or wrap them in a throwing 
function). The first error that occurs breaks the chain and switches control to the catch 
block (or propagates the error to the caller): 

func checkFilesAndFetchProcesslD(filenames: [String]) -> Int { 

do { 

try filenames.all(matching: checkFile) 

let pidString = try contents(ofFile: "Pidfile") 

return try lnt(pidString).or(error: ReadlntError.couldNotRead) 

} catch { 

return 42 //Default value 

} 

} 


Chaining Result 

To see how well Swift’s native error handling matches up against other error handling 
schemes, let’s compare this to an equivalent example based on the Result type. Chaining 
multiple functions that return a Result — where the input to the second function is the 
result of the hrst — is a lot of work if you want to do it manually. To do so, you call the 
first function and unwrap its return value; if it’s a .success, you can pass the wrapped 
value to the second function and start over. As soon as one function returns a .failure, 
the chain breaks and you short-circuit by immediately returning the failure to the caller. 

To refactor this, we should turn the common steps of unwrapping the Result, 
short-circuiting in case of failure, and passing the value to the next transformation in 
case of success, into a separate function. That function is the flatMap operation. Its 
structure is identical to the existing flatMap for optionals that we covered in the 
optlonals chapter; 


extension Result { 

func flatMap<B>(transform: (A) -> Result<B>) -> Result<B> { 

switch self { 

case let .failure(m): return .failure(m) 
case let .success(x): return transform(x) 

} 

} 

} 

With this in place, the end result is quite elegant: 

func checkFilesAndFetchProcesslD(filenames: [String]) -> Result<lnt> { 
return filenames 
.all(matching: checkFile) 

•flatMap { _ in contents(ofFile: "Pidfile") } 

•flatMap {contents in 
I nt(contents).map(Resu It.success) 

?? .failure(ReadlntError.couldNotRead) 

} 

} 

(We’re using variants of all(matching:), checkFile, and contents(ofFile:) here that return 
Result values. The implementations aren’t shown here.) 

But you can also see that Swift’s error handling stands up extremely well. It’s shorter, 
and it’s arguably more readable and easier to understand. 


Higher-Order Functions and Errors 

One domain where Swift’s error handling unfortunately does not work very well is 
asynchronous APIs that need to pass errors to the caller in callback functions. Let’s look 
at a function that asynchronously computes a large number and calls back our code 
when the computation has finished: 

func compute(callback: (Int) -> ()) 

We can call it by providing a callback function. The callback receives the result as the 
only parameter: 


compute {result in 
print(result) 

} 

If the computation can fail, we could specify that the callback receives an optional 
integer, which would be nil In case of a failure: 

func computeOptional(callback: (Int?) -> ()) 

Now, in our callback, we must check whether the optional is non-nil, e.g. by using the ?? 
operator: 

computeOptional {result in 
print(result??-1) 

} 

But what if we want to report specihc errors to the callback, rather than just an optional? 
This function signature seems like a natural solution: 

func computeThrows(callback: (int) throws -> ()) 

But this type has a totally different meaning. Instead of saying that the computation 
might fall, it expresses that the callback itself could throw an error. This highlights the 
key difference we mentioned earlier: optionals and Result work on types, whereas 
throws works only on function types. Annotating a function with throws means that the 
function might fail. 

It becomes a bit clearer when we try to rewrite the wrong attempt from above using 
Result: 

func computeResult(callback: (Int) -> Result<()>) 

This isn’t correct either. We need to wrap the Int argument in a Result, not the callback’s 
return type. Finally, this is the correct solution: 

func computeResult(callback: (Result<lnt>) -> ()) 

Unfortunately, there’s currently no clear way to write the variant above with throws. The 
best we can do is wrap the Int inside another throwing function. This makes the type 
more complicated: 


func compute(callback: (() throws -> Int) -> ()) 


And using this variant becomes more difficult for the caller too. In order to get the 
integer out, the callback now has to call the throwing function. This is where the caller 
must perform the error checking: 

compute {(resultFunc: () throws -> Int) in 

do { 

let result = try resultFuncQ 
print(result) 

} catch { 

printC'An error occurred: \(error)'') 

} 

} 

This works, but it’s definitely not idiomatic Swift; Result is the way to go for 
asynchronous error handling. It’s unfortunate that this creates an impedance mismatch 
with synchronous functions that use throws. The Swift team has expressed interest in 
extending the throws model to other scenarios, but this will likely be part of the much 
greater task of adding native concurrency features to the language, and that won’t 
happen until Swift 5 at the earliest. 

Until then, we’re stuck with using our own custom Result types. Apple did consider 
adding a Result type to the standard library, but ultimately decided against it on the 
grounds that it wasn’t independently valuable enough outside the error handling 
domain and that the team didn’t want to endorse it as an alternative to throws-style 
error handling. Luckily, using Result for asynchronous APIs is a pretty well-established 
practice among the Swift developer community, so you shouldn’t hesitate to use it in 
your APIs when the native error handling isn’t appropriate. It certainly beats the 
Objective-C style of having completion handlers with two nullable arguments (a result 
object and an error object). 


Recap 

When Apple introduced its error handling model in Swift 2.0, a lot of people in the 
community were skeptical. People were rolling their own Result types in the Swift 1.x 
days, mostly with a typed error case. The fact that throws uses untyped errors was seen 
as a needless deviation from the strict typing in other parts of the language. 
Unsurprisingly, the Swift team had considered this very carefully and intentionally went 



for untyped errors. We were skeptical too, but in hindsight, we think the Swift team was 
proven correct, not least by the large acceptance of the error handling modei in the 
deveioper community. 

There’s a chance that strongiy typed error handling will be added as an opt-in feature in 
the future, along with better support for asynchronous errors and passing errors around 
as values. As it stands now, error handling is a good example of Swift being a pragmatic 
language that optimizes for the most common use case first. Keeping the syntax familiar 
for developers who are used to C-style languages is a more important goal than adhering 
to the “purer” functional style based on Result and flatMap. 

In the meantime, we now have many possible choices for handling the unexpected in 
our code. When we can’t possibly continue, we can use fatalError or an assertion. When 
we’re not interested in the kind of error, or if there’s only one kind of error, we can use 
optionals. When we need more than one kind of error or want to provide additional 
information, we can use Swift’s built-in errors or write our own Result type. When we 
want to write functions that take a function as a parameter, rethrows lets us write one 
variant for both throwing and non-throwing function parameters. Finally, the defer 
statement is very useful in combination with the built-in errors, defer statements 
provide us with a single place to put our cleanup code, regardless of how a scope exits 
normally or with an error. 



Generics 




Like most modern languages, Swift has a number of features that can all be grouped 
under genen'c programming. Generic code allows you to write reusable functions and 
data types that can work with any type that matches the constraints you dehne. For 
example, types such as Array and Set are generic over their elements. Generic functions 
are generic over their input and/or output types. The declaration 

func identity<A>(input: A) -> A defines a function that works on any type, identihed by the 
placeholder A. In a way, we can also think of protocols with an associated type as 
“generic protocols.” The associated type allows us to abstract over specihc 
implementations. IteratorProtocol is an example of such a protocol: It’s generic over the 
Element type it produces. 

The goal of generic programming is to express the essential interface an algorithm or 
data structure requires. For example, consider the lastfwhere:) method we wrote in the 
built-in collections chapter. Writing this method as an extension on Array would’ve been 
the obvious choice, but an Array has lots of capabilities lastfwhere:) doesn’t need. By 
asking ourselves what the essential interface is — that is, the minimal set of features 
required to implement the desired functionality — we can make the function available 
to a much broader set of types. In this example, last(where:) has only one requirement: it 
needs to traverse a sequence of elements in reverse order. This makes an extension on 
Sequence the right place for this algorithm (and we can add a more efficient variant to 
BidirectionalCollection). 

In this chapter, we’ll look at how to write generic code. We’ll start by talking about 
overloading because this concept is closely related to generics. We’ll use generic 
programming to provide multiple implementations of an algorithm, each relying on a 
different set of assumptions. We’ll also discuss some common difficulties you may 
encounter when writing generic algorithms for collections. We’ll then look at how you 
can use generic data types to refactor code to make it testable and more flexible. Finally, 
we’ll cover how the compiler handles generic code and what we can do to get the best 
performance for our own generic code. 


Overloading 

Overloaded functions, i.e. multiple functions that have the same name but different 
argument and/or return types, are not generic per se. But like generics, they allow us to 
make one Interface available to multiple types. 



Overload Resolution for Free Functions 


For example, we could define a function named raise(_:to:) to perform exponentiation 
and provide separate overloads for Double and Float arguments: 

func raiseL base: Double, to exponent: Double) -> Double { 
return pow(base, exponent) 

} 

func raiseL base: Float, to exponent: Float) -> Float { 
return powf(base, exponent) 

} 

We used the pow and powf functions declared In Swift’s Darwin module (or Gllbc on 
Linux) for the Implementations. 

When the raise function is called, the compiler picks the correct overload based on the 
types of the arguments and/or the return value: 

let double = raise(2.0, to: 3.0)//8.0 
type(of: double) /'Double 
let float: Float = raise(2.0, to: 3.0) Z'8.0 
type(of: float) // Float 

Swift has a complex set of rules for which overloaded function to pick, which is based on 
whether or not a function is generic and what kind of type is being passed in. While the 
rules are too long to go Into here, they can be summarized as “pick the most specific 
one.” This means that non-generic functions are picked over generic ones. 

As an example, consider the following function that logs certain properties of a view. We 
provide a generic implementation for U I View that logs the view’s class name and frame, 
and a specific overload for UI Label that prints the label’s text: 

func log<View: UIView>(_ view: View) { 
printC'it's a \(type(of: view)), frame: \(view.frame)") 

} 

func log(_ view: UiLabel) { 
let text = view.text ?? "(empty)" 
printC'it's a label, text: \(text)'') 

} 


Passing a UI Label will call the label-specific overload, whereas passing any other view 
will use the generic one: 

let label = UILabel(frame: CGRectfx: 20, y: 20, width: 200, height: 32)) 

label.text = "Password" 

log(label) // It'sa label, text: Password 

let button = UIButtonfframe: CGRectfx: 0, y: 0, width: 100, height: 50)) 
log(button) /'/t's a UlButton, frame: (0.0, 0.0, 100.0, 50.0) 

It’s important to note that overloads are resolved statically at compile time. This means 
the compiler bases its decision of which overload to call on the static types of the 
variables Involved, and not on the values’ dynamic types at runtime. This is why the 
generic overload of log will be used for both views if we put the label and the button into 
an array and then call the log function in a loop over the array’s elements: 

let views = [label, button] //Type of views is [UiView] 
for view in views { 
log(view) 

} 

/* 

It's a UlLabel, frame: (20.0,20.0,200.0, 32.0) 

It's a UlButton, frame: (0.0, 0.0, 100.0, 50.0) 

*/ 


The static type of the view variable is UlView; it’s irrelevant that the dynamic type 
UlLabel would result in a different overload at runtime. 

If instead you need runtime polymorphism — that is, you want the function to be picked 
based on what a variable points to and not what the type of the variable is — you should 
be using methods not functions, i.e. define log as a method on UlView and UlLabel. 


Overload Resolution for Operators 

The compiler exhibits some surprising behavior when it comes to the resolution of 
overloaded operators. As Matt Gallagher points out, the type checker always favors 
non-generic overloads over generic variants, even when the generic version would be 
the better choice (and the one which would be chosen if we were talking about a normal 
function). 



Going back to the exponentiation example from above, let’s define a custom operator 
named ** for the same operation: 

//Exponentiation has higher precedence than multiplication 
precedencegroup ExponentiationPrecedence { 
associativity: left 

higherThan: MultiplicationPrecedence 

} 

infix operator **: ExponentiationPrecedence 

func **(lhs: Double, rhs: Double) -> Double { 
return pow(lhs, rhs) 

} 

func **(lhs: Float, rhs: Float) -> Float { 
return powf(lhs, rhs) 

} 

2.0 **3.0//8.0 


The above code is equivalent to the raise function we implemented in the previous 
section. Let’s add another overload for integers next. We want exponentiation to work 
for all integer types, so we define a generic overload for all types conforming to 
Binaryinteger: 

func **<l: Binarylnteger>(lhs: I, rhs: 1) -> I { 

//Cast to IntBA, use Double overload to compute result 
let result = Double(lnt64(lhs)) ** Double(lnt64(rhs)) 
return l(result) 

} 

This looks like it should work, but if we now call ** with two integer literals, the compiler 
complains about an ambiguous use of the ** operator: 

2 ** 3 // Error: Ambiguous use of operator '**' 

The explanation for why this happens brings us back to what we said at the beginning of 
this section: when resolving overloaded operators, the type checker always favors 
non-generic overloads over generic overloads. Apparently, the compiler ignores the 
generic overload for integers and then raises the error because It can’t decide whether it 
should call the overload for Double or the one for Float — both are equally valid choices 
for two Integer literal arguments. To convince the compiler to pick the correct overload. 


we have to explicitly mark at least one of the arguments as an integer type or else 
provide an explicit result type: 

let intResuit: Int = 2 ** 3 //8 

The compiler only behaves in this manner for operators — a generic overload of the raise 
function for Binaryinteger would work just fine without introducing ambiguities. The 
reason for this discrepancy comes down to performance: the Swift team considers the 
reduction of complexity the type checker has to deal with significant enough to warrant 
the use of this simpler but sometimes incorrect overload resolution model for operators. 


Overloading with Generic Constraints 

You’ll often encounter overloading in conjunction with generic code when the same 
operation can be expressed with multiple algorithms that each require different 
constraints on their generic parameters. Suppose we want to determine if all the entries 
in one array are also contained in another. In other words, we want to find out if the first 
array is a subset of the second (keeping in mind that the element order is 
inconsequential). The standard library provides a method named isSubset(of:) that does 
this, but only for types that conform to the SetAlgebra protocol, such as Set. 

If we wanted to write a version of isSubset(of:) that works with a broader set of types, it’d 
look something like this: 

extension Sequence where Element: Equatable { 

///Returns true iff ail elements in 'self are also in 'other'. 
func isSubset(of other: [Element]) -> Bool { 
for element in self { 
guard other.contains(element) else { 
return false 

} 

} 

return true 

} 


let oneToThree = [1,2,3] 

letfiveToOne = [5,4,3,2,1] 

oneToThree.isSubset(of: fiveToOne) /^true 


isSubset is defined as an extension on the Sequence protocol, where the elements of the 
sequence are Equatable. It takes an array of the same type to check against, and it 
returns true if every single element in the receiver is also a member of the argument 
array. The method doesn’t care about what the elements are, just so long as they 
conform to Equatable, because only equatable types can be used with contains. The 
element type can be an Int, a String, or your own custom user-defined class, just so long 
as it’s equatable. 

This version of isSubset comes with a big downside, which is performance. The 
algorithm has performance characteristics of 0(nm), where n and m are the element 
counts of the two arrays. That is, as the input sizes grow, the worst-case time the 
function takes to run grows quadratically. This is because contains runs in linear time 
on arrays, i.e. 0(m). This makes sense if you think about what it needs to do: loop over 
the contents of the source sequence, checking if they match a given element. But our 
algorithm calls contains inside another loop — the one over the receiver’s elements — 
which also runs in linear time in a similar fashion. And running an 0(m) loop inside an 
0(n) loop results in an 0(nm) function. 

We can write a better-performing version by tightening the constraints on the sequence’s 
element type. If we require the elements to conform to Hashable, we can convert the 
other array into a Set, taking advantage of the fact that a set performs lookups in 
constant time: 

extension Sequence where Element: Hashable { 

///Returns true iff all elements in 'self are also in 'other'. 
func isSubsetfof other: [Element]) -> Bool { 
let otherSet = Set(other) 
for element in self { 

guard OtherSet.contains(element) else { 
return false 

} 

} 

return true 

} 


With the contains check taking 0(1) time (assuming a uniform distribution of the 
hashes), the entire for loop now becomes 0(n) — the time required grows linearly with 
the number of elements in the receiver. The additional cost of converting other into a set 
is 0(m), but we incur it only once, outside the loop. Thus, the total cost becomes 


0{n + m), which is much better than the 0(nm) for the Equatabie version — if both 
arrays have 1,000 eiements, it’s the difference between 2,000 and one miiiion iterations. 

So now we have two versions of the aigorithm, none of which is cieariy better than the 
other — one is faster, and the other works with a wider range of types. The good news is 
that you don’t have to pick one of these options. You can impiement both overioads of 
isSubset and iet the compiier seiect the most appropriate one based on the argument 
types. Swift is very fiexibie about overioading — you can overioad not just by input type 
or return type, but aiso based on different constraints on a generic piacehoider, as seen 
in this exampie. 

The generai ruie that the type checker wiii pick the most specific overioad it can find 
aiso appiies here. Both versions of isSubset are generic, so the ruie that non-generic 
variants are favored over generic ones is no heip. But the version that requires the 
eiements to be Hashabie is more specific, because Hashabie extends Equatabie, and thus 
it imposes more constraints. Given that these constraints are probabiy there to make the 
aigorithm more efficient — as they are in the case of isSubset — the compiier works on 
the assumption that the more specific function is the better choice. 

There’s another way in which isSu bset can be made more generai. Up untii now, it’s oniy 
taken an array of eiements to check against. But Array is a specific type. Reaiiy, isSubset 
doesn’t need to be this specific. Across the two versions, there are oniy two function 
caiis: contains in both, and Set.init inthe Hashable version. In both cases, these 
functions only require an input type that conforms to the Sequence protocoi: 

extension Sequence where Element: Equatabie { 

///Returns a Boolean value indicating whether the sequence contains the 
///given element. 

func containsL element: Element) -> Bool 

} 

struct Set<Element: Hashable>: 

SetAlgebra, Hashable, Collection, ExpressibleByArrayLiteral 

{ 

///Creates a new set from a finite sequence of items. 
init<Source: Sequence>L sequence: Source) 
where Source.Element == Element 

} 

Given this, the oniy thing isSubset needs is for other to be of some type that also 
conforms to Sequence. What’s more is that the two sequence types — self and other — 


don’t have to be the same. They just need to be sequences of the same element. So here’s 
the Hashable version, rewritten to operate on any two kinds of sequence: 

extension Sequence where Element: Hashable { 

///Returns true iff all elements in 'self are also in 'other'. 
func isSubset<S: Sequence>(of other: S) -> Bool 
where S.Element == Element 

{ 

let otherSet = Set(other) 
for element in self { 

guard OtherSet.contains(element) else { 
return false 

} 

} 

return true 

} 


Now that the two sequences don’t have to be the same type, this opens up a lot more 
possibilities. For example, you could pass in a CountableRange of numbers to check 
against: 

[5,4,3].isSubset(of: 1 ...10) // true 

A similar change can be made to the version that requires the elements to be equatable 
(not shown here). 


Parameterizing Behavior with Closures 

The isSubset method is still not as general as it could be. What about sequences where 
the elements aren’t equatable? Arrays, for example, aren’t equatable, and if we use them 
as elements, it won’t work with our current implementation. Arrays do have an = = 
operator, defined like this: 

///Returns true if these arrays contain the same elements. 

func = = <Element: Equatable>(lhs: [Element], rhs: [Element]) -> Bool 

But that doesn’t mean you can use them with isSubset: 

// Error: Type of expression is ambiguous without more context 


[[1,2]].isSubset(of: [[1,2], [3,4]]) 


This is because Array doesn’t conform to Equatable. It can’t, because the type the array 
contains might not, itseif, be equatabie. Swift currentiy iacks support for conditional 
protocol conformance, i.e. the abiiity to express the idea that Array (or any Sequence) 
oniy conforms to a protocoi when certain constraints, such as Element: Equatable, are 
met. So Array can provide an impiementation of == for when the contained type is 
equatabie, but it can’t conform to the protocoi. 

So how can we make isSubset work with non-equatabie types? We can do this by giving 
controi of what equaiity means to the caiier, requiring them to suppiy a function to 
determine equaiity. For exampie, the standard iibrary provides a second version of 
contains that does this: 

extension Sequence { 

///Returns a Boolean value indicating whether the sequence contains an 
///element that satisfies the given predicate. 
func contains(where predicate: (Element) throws -> Bool) 
rethrows -> Bool 

} 

That is, it takes a function that takes an eiement of the sequence and performs some 
check. It runs the check on each element, returning true as soon as the check returns 
true. This version of contains is much more powerfui. For exampie, you can use it to 
check for any condition inside a sequence: 

let isEven = {$0%2==0} 

(0..<5).contains(where: isEven) //true 
[1,3,99].contains(where: isEven) /^fo/se 

We can leverage this more flexible version of contains to write a similarly flexible version 
of isSubset: 

extension Sequence { 
func isSubset<S: Sequence>(of other: S, 
by areEquivalent: (Element, S.Element) -> Bool) -> Bool 

{ 

for element in self { 

guard other.contains(where: {areEquivalent(element, $0)}) else { 
return false 

} 


} 

return true 


} 

} 

Now, we can use isSubset with arrays of arrays by supplying a closure expression that 
compares the arrays using ==. Unfortunately, if we import Foundation, another 
performance optimization for the type checker confuses the compiler so that it no 
longer knows which version of = = to use. So we need a type annotation somewhere in 
the code: 

[[1,2]].isSubset(of: [[1,2] as [Int], [3,4]]) {$0 == $1 } //true 

The two sequences’ elements don’t even have to be of the same type, so long as the 
supplied closure handles the comparison: 

let ints = [1,2] 

let strings = ["1 ","2'',"3"] 

ints.isSubset(of: strings) {String($0) == $1 } //true 


Operating Generically on Collections 

Generic algorithms on collections often pose some special problems, particularly when 
it comes to working with indices and slices. In this section, we’d like to demonstrate how 
to deal with these problems by showing two examples that heavily rely on the correct 
handling of indices and slices. 


A Binary Search 

Suppose you hnd yourself in need of a binary search algorithm for collections. You reach 
for your nearest favorite reference, which happens to be written in Java, and port the 
code to Swift. Here’s one such attempt — albeit a boringly iterative, rather than 
recursive, one: 

extension Array { 

/// Returns the first index where 'value' appears in 'self, or 'nil', 

/// if 'value' is nat found. 

/// 




/// - Requires: 'arelnIncreasingOrder' is a strict weak ordering over the 
///elements in 'self, and the elements in the array are already 
/// ordered by it. 

/// - Complexity: O(log 'count') 
func binarySearch(for value: Element, 
arelnIncreasingOrder: (Element, Element) -> Bool) -> int? 

{ 

var left = 0 
var right = count - 1 
while left <= right { 
let mid = (left + right) / 2 
let candidate = self[mid] 
if areinincreasingOrder(candidate,value) { 
left = mid + 1 

} else if areinincreasingOrder(value,candidate) { 
right = mid - 1 
} else { 

// If neither element comes before the other, they _must_ be 
// equal, per the strict ordering requirement of arelnIncreasingOrder 

return mid 

} 

} 

// Not found 

return nil 

} 


extension Array where Element: Comparable { 
func binarySearch(for value: Element) -> int? { 
return self.binarySearch(for: value, arelnIncreasingOrder: <) 

} 

} 


For such a famous and seemingly simple algorithm, a binary search is 
notoriously hard to get right . This one contains a bug that also existed in the 
Java implementation for two decades — one weTl fix in the generic version. 
But we also don’t guarantee that it’s the only bug! 




It’s worth noting some of the conventions from the Swift standard iihrary that this 
foilows: 

-> Simiiar to index(of:), it returns an optionai index, with nil representing “not 
found.” 

-> It’s dehned twice — once with a user-supplied parameter to perform the 
comparison, and once relying on Comparable conformance to supply that 
parameter as a convenience to callers. 

-> The ordering must be a strict weak ordering. This means that when comparing 
two elements, if neither is ordered before the other, they must be equal. 

This works for arrays, but if you wanted to binary search a ContiguousArray or an 
ArraySlice, you’re out of luck. The method should really be in an extension to 
RandomAccessCollection — the random access is necessary to preserve the logarithmic 
complexity, as you need to be able to locate the midpoint in constant time. 

A shortcut might be to require the collection to have an Int index. This will cover almost 
every random-access collection in the standard library, and it means you can cut and 
paste the entire Array version as is: 

extension RandomAccessCollection where Index == Int, IndexDistance == Int { 
public func binarySearch(for value: Element, 
arelnIncreasingOrder: (Element, Element) -> Bool) 

-> Index? 

{ 

// Identical implementation to that of Array... 

} 

} 

Warning: If you do this, you’ll introduce an even worse bug, which we’ll come to shortly. 

But this is still restricted to integer-indexed collections, and collections don’t always 
have an integer index. Dictionary, Set, and the various String collection views have 
custom index types. The most notable random-access example in the standard library is 
Reversed RandomAccessCollection, which, as we saw in the collection protocols chapter, 
has an opaque index type that wraps the original index, converting it to the equivalent 
position in the reversed collection. 


Generic Binary Search 


If you lift the requirement for an Int index, you’li hit severai compiier errors. The code 
needs some rewrites in order to be fully generic, so here’s a fully generic version: 

extension RandomAccessCoUection { 
public func binarySearch(for value: Element, 
arelnIncreasingOrder: (Element, Element) -> Bool) -> Index? 

{ 

guard lisEmpty else {return nil} 
var left = startindex 
var right = index(before: endindex) 
while left <= right { 
let dist = distance(from: left, to: right) 
let mid = index(left, offsetBy: dist/2) 
let candidate = self[mid] 
if arelnlncreasingOrder(candidate, value) { 
left = index(after: mid) 

} else if arelnlncreasingOrder(value, candidate) { 
right = index(before: mid) 

} else { 

// If neither element comes before the other, they _must_ be 
// equal, per the strict ordering requirement of arelnIncreasingOrder 

return mid 

} 

} 

// Not found 

return nil 

} 


extension RandomAccessCoUection where Element: Comparable { 
func binarySearch(for value: Element) -> Index? { 
return binarySearch(for: value, arelnIncreasingOrder: <) 

} 

} 

The changes are small but significant. First, the left and right variables have changed 
type to no longer be integers. Instead, we’re using the start and end index values. These 
might be integers, but they might also be opaque types like String’s index type (or 
Dictionary’s or Set’s, not that these are random access). 


But secondly, the simple statement (left + right) / 2 has been replaced by the slightly 
uglier index(left, offsetBy: dist/2), where let dist = distance(from: left, to: right). How 
come? 

The key concept here is that there are actually two types involved in this calculation: 
index and indexDistance. These are not necessarily the same thing. When using integer 
indices, we happen to be able to use them interchangeably. But loosening that 
requirement breaks this. 

The distance is the number of times you’d need to call index(after:) to get from one point 
in the collection to another. The end index must be “reachable” from the start index — 
there’s always a finite integer number of times you need to call index(after:) to get to it. 
This means IndexDistance must be an integer (though not necessarily an Int), and the 
corresponding constraint in the definition of Collection is (the constraint is actually 
defined in_indexable, and Collection inherits from_indexable): 

public protocol Collection:/*... */{ 

////^ type that can represent the number of steps between a pair of 
///indices. 

associatedtype IndexDistance: Signedinteger = Int 

} 

This is also why we need an extra guard to ensure the collection isn’t empty. When you’re 
just doing integer arithmetic, there’s no harm in generating a right value of -1 and then 
checking that it’s less than zero. But when dealing with any kind of index, you need to 
make sure you don’t move back through the start of the collection, which might be an 
invalid operation. (For example, what would happen if you tried to go back one from the 
start of a doubly linked list?) 

Being integers, index distances can be added together or divided to find the remainder. 
What we can’t do is add two indices of any kind together, because what would that 
mean? If you had the Words collection from the collection protocols chapter, you 
obviously couldn’t “add” two indices together and divide by two. Instead, we must think 
only in terms of moving indices by some distance using index(after:), index(before:), or 
index(_:offsetBy:). 

This way of thinking takes some getting used to if you’re accustomed to thinking in 
terms of arrays. But think of many array index expressions as a kind of shorthand. For 
example, when we wrote let right = count -1, what we really meant was 
right = index(startlndex, offsetBy: count - 1). It’s just that when the index is an Int and 
startindex is zero, this reduces to 0 + count - 1, which in turn reduces to count - 1. 


This leads us to the serious bug in the implementation that took our Array code and just 
applied it to RandomAccessCoUection: collections with integer indices don’t necessarily 
start with an index of zero, the most common example being ArraySlice. A slice created 
via myArray[3..<5] will have a startindex of three. Try and use our simplistic generic 
binary search on it, and it’ll crash at runtime. While we were able to require that the 
index be an integer, the Swift type system has no good way of requiring that the 
collection be zero-based. And even if it did, in this case, it’d be a silly requirement to 
impose, since we know a better way. Instead of adding together the left and right indices 
and halving the result, we hnd half the distance between the two, and then we advance 
the left index by that amount to reach the midpoint. 


This version also Axes the bug in our initial Implementation. If you didn’t spot 
it, it’s that if the array is extremely large, then adding two integer indices 
together might overflow before being halved (suppose count was approaching 
Int.max and the searched-for element was the last one in the array). On the 
other hand, when adding half the distance between the two indices, this 
doesn’t happen. Of course, the chances of anyone ever hitting this bug is very 
low, which is why the bug in the Java standard library took so long to be 
discovered. 


Now, we can use our binary search algorithm to search 
Reversed RandomAccessCoUection: 

let a = ["a", "b", "c", "d", "e", "f", "g"] 
let r = a.reversedO 

r. binarySearch(for: "g", arelnIncreasingOrder: >) == r.startindex//true 

And we can also search slices, which aren’t zero-based: 

let s = a[2..<5] 

s. startindex 

s.binarySearch(for: "d") //0ptional(3) 


Shuffling Collections 

To help cement this concept, here’s another example, this time an implementation of 
the Fisher-Yates shuffling algorithm: 




extension Array { 
mutatingfunc shuffleQ { 
for i in 0..<(count -1) { 

let j = lnt(arc4random_uniform(Ulnt32(count - i))) + i 
self.swapAt(i, j) 

} 

} 

/// Non-mutating variant of 'shuffle' 
func shuffledQ -> [Element] { 
var clone = self 
clone.shuffleO 
return clone 

} 


Again, we’ve followed a standard library practice: providing an in-place version, since 
this can be done more efficiently, and then providing a non-mutating version that 
generates a shuffled copy of the array, which can be implemented in terms of the 
in-place version. 

So how can we write a generic version of this that doesn’t mandate integer indices? Just 
like with binary search, we still need random access, but we also have a new 
requirement that the collection be mutable, since we want to be able to provide an 
in-place version. The use of count -1 will definitely need to change in a way similar to 
the binary search. 

Before we get to the generic implementation, there’s an extra complication. We want to 
use arc4random_uniform to generate random numbers, but we don’t know exactly what 
type of integer IndexDistance will be. We know it’s an integer, but not necessarily that 
It’s an Int. To handle this, we need to write a generic version of arc4random_uniform that 
works on any integer type conforming to the Binaryinteger protocol (Swift 4 
implemented a new hierarchy of protocol-oriented Integers , which makes this task 
easier than before): 

extension Binaryinteger { 

static func arc4random_uniform(_ upper_bound: Self) -> Self { 
precondition( 

upper_bound > 0 && Ulnt32(upper_bound) < Ulnt32.max, 

''arc4random_uniform only callable up to \(Ulnt32.max)") 
return Self(Darwin.arc4random_uniform(Ulnt32(upper_bound))) 



} 


} 


You could write a version of arcArandom that operates on ranges spanning 
negative numbers, or above the max of Ulnt32, if you wanted to. But to do 
so would require a iot more code. If you’re interested, the definition of 
arc4random_uniform is actualiy open source and quite weil commented, and it 
gives several clues as to how you might do this. 


We then use the ability to generate a random number for every IndexDistance type in our 
generic shuffle implementation: 

extension MutableCollection where Self: RandomAccessCoUection { 
mutatingfunc shuffleQ { 
var i = startindex 

let beforeEndIndex = indexfbefore: endindex) 
while i < beforeEndIndex { 
let dist = distanceffrom: i, to: endindex) 

let randomDistance = IndexDistance.arc4random_uniform(dist) 
let j = indexfi, offsetBy: randomDistance) 
self.swapAtfi, j) 
formindexfafter: &i) 

} 

} 


extension Sequence { 
func shuffledQ -> [Element] { 
var clone = Array(self) 
clone.shuffleO 
return clone 

} 

} 

var numbers = Array(1...10) 

numbers.shuffleO 

numbers //[10, 5, 9, 4, 3,6,7,8,1,21 




The generic shuffle method is signiflcantiy more compiex and iess readabie than the 
non-generic version. This is partiy because we had to repiace simpie integer math iike 
count -1 with index caicuiations iike index(before: endindex). The other reason is that 
we switched from a for to a while loop. The alternative, iterating over the indices with 
for i in indices.dropLastO, has a potential performance problem that we already talked 
about in the collection protocols chapter: if the indices property holds a reference to the 
collection, mutating the collection while traversing the indices will defeat the 
copy-on-write optimizations and cause the collection to make an unnecessary copy. 

Admittedly, the chances of this happening in our case are small, because most 
random-access collections likely use plain integer indices where the indices type doesn’t 
need to reference its base collection. For instance. Array.indices is CountableRange<int> 
instead of the default DefaultRandomAccessindices. 

Inside the loop, we measure the distance from the running index to the end and then use 
our new Binaryinteger.arc4random_uniform method to compute a random index to swap 
with. The actual swap operation remains the same as it is in the non-generic version. 

You might wonder why we didn’t extend MutableCollection when implementing the 
non-modifying shuffle. Again, this is a pattern you see often in the standard library — 
for example, when you sort a ContiguousArray, you get back an Array and not a 
ContiguousArray. 

In this case, the reason is that our immutable version relies on the ability to clone the 
collection and then shuffle it in place. This, in turn, relies on the collection having value 
semantics. But not all collections are guaranteed to have value semantics. If 
NSMutableArray conformed to MutableCollection (which it doesn’t — probably because 
it’s bad form for Swift collections to not have value semantics — but could), then 
shuffled and shuffle would have the same effect, since NSMutableArray has reference 
semantics, var clone = self just makes a copy of the reference, so a subsequent 
clone.shuffle would shuffle self — probably not what the user would expect. Instead, we 
take a full copy of the elements into an array and shuffle and return that. 

There’s a compromise approach. You could write a version of shuffle to return the same 
type of collection as the one being shuffled, so long as that type is also a 
RangeReplaceableCollection: 

extension MutableCollection 

where Self: RandomAccessCollection, Self: RangeReplaceableCollection 

{ 

func shuffledQ -> Self { 


var clone = SelfQ 
clone.append(contentsOf: self) 
clone.shuffleO 
return clone 

} 

} 


This relies on the two abilities of RangeReplaceabieCollection: to create a fresh empty 
version of the collection, and to then append any sequence (in this case, self) to that 
empty collection, thus guaranteeing a full clone takes place. The standard library 
doesn’t take this approach — probably because the consistency of always creating an 
array for any kind of non-in-place operation is preferred — but it’s an option if you want 
it. However, remember to create the sequence version as well, so that you offer shuffling 
for non-mutable collections and sequences. 


Designing with Generics 

As we’ve seen, generics can be used to provide multiple implementations of the same 
functionality. We can write generic functions but provide specihc implementations for 
certain types. Also, by using protocol extensions, we can write generic algorithms that 
operate on many types. 

Generics can also be very helpful during the design of your program, in order to factor 
out shared functionality and reduce boilerplate. In this section, we’ll refactor a normal 
piece of code, pulling out the common functionality by using generics. Not only can we 
make generic functions, but we can also make generic data types. 

Let’s write some functions to interact with a web service. For example, consider fetching 
a list of users and parsing it into the User datatype. We write a function named 
loadUsers, which loads the users from the network asynchronously and then calls a 
callback with the list of fetched users. 

We start by implementing it in a naive way. First, we build the URL. Then, we load the 
data synchronously (this is just for the sake of the example; you should always do 
networking asynchronously in production code). Next, we parse the JSON response, 
which gives us an array of dictionaries. Finally, we transform the plain JSON objects into 
Userstructs: 


func loadUsers(callback: ([User]?) -> ()) { 


let usersURL = webserviceURL.appendingPathComponent("/users'') 
let data = try? Data(contentsOf: usersURL) 
let json = data.flatMap { 

try? JSONSerialization.jsonObject(with: $0, options: []) 

} 

let users = (json as? [Any]).flatMap {jsonObject in 
jsonObject.flatMap(User.init) 

} 

callback(users) 

} 

Notice that we don’t take advantage of the Codable system we discussed in the chapter 
on encoding and decoding here. We use the “old-fashioned” way of parsing JSON into a 
dictionary with JSONSerialization, and then the User type knows how to initialize itself 
from a JSON dictionary. 

The loadUsers function has three possible error cases: the URL loading can fail, the 
JSON parsing can fail, and building user objects from the JSON array can fail. All three 
operations return nil upon failure. By using flatMap on the optional values, we ensure 
that subsequent operations are only executed if the previous ones succeeded. Otherwise, 
the nil value from the first failing operation will be propagated through the chain to the 
end, where we eventually call the callback either with a valid users array or nil. 

Now, if we want to write the same function to load other resources, we’d need to 
duplicate most of the code. For example, if we consider a function to load blog posts, its 
type could look like this: 

func loadBlogPosts(callback: ([BlogPost])? -> ()) 

The implementation would be almost the same. Not only would we have duplicated 
code, but both functions are hard to test: we need to make sure the test can access the 
web service or else find some way to fake the requests. And because the functions take a 
callback, we need to make the tests asynchronous too. 


Extracting Common Functionality 

A better approach is to try to move the User-specific parts outside the function in order 
to make the other parts reusable. For example, we could add the path and the conversion 
function that turns JSON objects into domain objects as parameters. We name this new 


function load Resource to indicate its universality. Because we want the conversion 
function to handle arbitrary types, we also make the function generic over A: 

func loadResource<A>(at path: String, 
parse: (Any) -> A?, callback: (A?) -> ()) 

{ 

let resourceURL = webserviceURL.appendingPathComponent(path) 
let data = try? Data(contentsOf: resourceURL) 
let json = data.flatMap { 

try? JSONSerialization.jsonObject(with: $0, options: []) 

} 

callback(json.flat[Vlap(parse)) 

} 

Now we can base our loadUsers function on loadResource: 

func loadUsers(callback: ([User]?) -> ()) { 
loadResource(at: ''/users'', parse: jsonArray(User.init), callback: callback) 

} 

We use a helper function, jsonArray, to convert JSON into user objects. It first tries to 
convert an Any to an array of Anys, and then it tries to parse each element using the 
supplied function, returning nil if any of the steps fail: 

func jsonArray<A>(_ transform: ©escaping (Any) -> A?) -> (Any) -> [A]? { 
return {array in 

guard let array = array as? [Any] else { 
return nil 

} 

return array.flatMap(transform) 

} 


To load the blog posts, we just change the path and the parsing function: 

func loadBlogPosts(callback: ([BlogPost]?) -> ()) { 
loadResource(at: "/posts", parse: jsonArray(BlogPost.init), callback: callback) 

} 

This avoids a lot of duplication. And if we later decide to switch from synchronous to 
asynchronous networking, we don’t need to update either loadUsers or loadBlogPosts. 


But even though these functions are now very short, they’re still hard to test — they 
remain asynchronous and depend on the web service being accessible. 


Creating a Generic Data Type 

The path and parse parameters of the loadResource function are very tightly coupled; if 
you change one, you likely have to change the other too. Let’s bundle them up in a struct 
that describes a resource. Just like functions, structs (and other types) can also be 
generic: 

struct Resource<A> { 
let path:String 
let parse: (Any) -> A? 

} 

Now we can write an alternative version of loadResource as a method on Resource. It 
uses the resource’s properties to determine what to load and how to parse the result, so 
the only remaining argument is the callback function: 

extension Resource { 

func loadSynchronously(callback: (A?) -> ()) { 
let resourceURL = webserviceURL.appendingPathComponent(path) 
let data = try? Data(contentsOf: resourceURL) 
let json = data.flatMap { 

try? JSONSerialization.jsonObject(with: $0, options: []) 

} 

callback(json.flatMap(parse)) 

} 

} 

The previous top-level functions to load a specific resource now become instances of the 
Resource struct. This makes it very easy to add new resources without having to create 
new functions: 

let usersResource: Resource<[User]> = 

Resource(path: "/users", parse: jsonArray(User.init)) 
let postsResource: Resource<[BlogPost]> = 

Resource(path: "/posts", parse: jsonArray(BlogPost.init)) 


Adding a variant that uses asynchronous networking is now possible with minimal 
duplication. We don’t need to change any of our existing code describing the endpoints: 

extension Resource { 

func loadAsynchronouslyfcallback: ©escaping (A?) -> ()) { 
let resourceURL = webserviceURL.appendingPathComponent(path) 
let session = URLSession.shared 

session.dataTask(with: resourceURL) {data, response, error in 
let json = data.flatMap { 

try? JSONSerialization.jsonObject(with: $0, options: []) 

} 

callback(json.flatMap(self. parse)) 
j.resumeO 

} 

} 

Aside from the usage of the asynchronous URLSession API, the only material difference 
to the synchronous version is that the callback argument must now be annotated with 
©escaping because the callback function escapes the method’s scope. See the functions 
chapter if you want to learn more about escaping vs. non-escaping closures. 

We’ve now completely decoupled our endpoints from the network calls. We boiled down 
usersResource and postsResource to their absolute minimums so that they only 
describe where the resource is located and how to parse it. The design is also extensible: 
adding more conhguration options, such as the HTTP method or a way to add POST data 
to a request, is simply a matter of adding additional properties to the Resource type. 
(Specifying default values, e.g. GET for the HTTP method, helps keep the code clean.) 

Testing has become much simpler. The Resource struct is fully synchronous and 
independent of the network, so testing whether a resource is configured correctly 
becomes trivial. The networking code is still harder to test, of course, because it’s 
naturally asynchronous and depends on the network. But this complexity is now nicely 
isolated in the loadAsynchronously method; all other parts are simple and don’t involve 
asynchronous code. 

In this section, we started with a non-generic function for loading some data from the 
network. Next, we created a generic function with multiple parameters, significantly 
reducing duplicate code. Finally, we bundled up the parameters into a separate 
Resource data type. The domain-specific logic for the concrete resources is fully 
decoupled from the networking code. Changing the network stack doesn’t require any 
change to the resources. 


How Generics Work 


How do generics work from the perspective of the compiler? To answer this question, 
let’s take a closer look at the min function from the standard library (we took this 
example from the Optimizing Swift Performance session at Apple’s 2015 Worldwide 
Developers Conference): 

func min<T: Comparable>(_ x:T, _ y:T) -> T { 
return y<x?y:x 

} 

The only constraints for the arguments and return value of min are that all three must 
have the same type T and that T must conform to Comparable. Other than that, T could 
be anything — Int, Float, String, or even a type the compiler knows nothing about at 
compile time because it’s defined in another module. This means that the compiler 
lacks two essential pieces of information it needs to emit code for the function: 

-> The sizes of the variables of type T (including the arguments and return value). 

-> The address of the specific overload of the < function that must be called at 
runtime. 

Swift solves these problems by introducing a level of indirection for generic code. 
Whenever the compiler encounters a value that has a generic type, it boxes the value in a 
container. This container has a fixed size to store the value; if the value is too large to fit. 
Swift allocates it on the heap and stores a reference to it in the container. 

The compiler also maintains a list of one or more witness tables per generic type 
parameter: one so-called value witness table, plus one protocol witness table for each 
protocol constraint on the type. The witness tables (also called vtables) are used to 
dynamically dispatch function calls to the correct implementations at runtime. 

The value witness table is always present for any generic type. It contains pointers to the 
fundamental operations of the type, such as allocation, copying, and destruction. These 
can be simple no-ops or memcopies for primitive value types such as Int, whereas 
reference types include their reference counting logic here. The value witness table also 
records the size and alignment of the type. 

The record for the generic type T in our example will include one protocol witness table 
because T has one protocol constraint, namely Comparable. For each method or 
property the protocol declares, the witness table contains a pointer to the 



implementation for the conforming type. Any calls to one of these methods in the body 
of the generic function are then dispatched at runtime through the witness table. In our 
example, the expression y < x is dispatched in this way. 

The protocol witness tables provide a mapping between the protocols to which the 
generic type conforms (this is statically known to the compiler through the generic 
constraints) and the functions that implement that functionality for the specihc type 
(these are only known at runtime). In fact, the only way to query or manipulate the value 
in any way is through the witness tables. We couldn’t declare the min function with an 
unconstrained parameter <T> and then expect it to work with any type that has an 
implementation for <, regardless of Comparable conformance. The compiler wouldn’t 
allow this because there wouldn’t be a witness table for it to locate the correct < 
implementation. This is why generics are so closely related to protocols — you can’t do 
much with unconstrained generics except write container types like Array<Element> or 
Optional<Wrapped>. 

In summary, the code the compiler generates for the min function looks something like 
this (in pseudocode): 

func min<T: Comparable>(_ x: Box_T, _y: Box_T, 
valueWTableJf: Viable, comparableWTable_T: Viable) 

-> Box_I 

{ 

let xCopy = valueWIable_I.copy(x) 
let yCopy = valueWIable_I.copy(y) 

let result = comparableWIable_I.lessIhan(yCopy, xCopy) ?y :x 
valueWIable_I.release(xCopy) 
valueWIable_I.release(yCopy) 
return result 

} 


The layout of the container for generic parameters is similar but not identical 
to the existential containers used for protocol types that we’ll cover in the next 
chapter. An existential container combines the storage for the value and the 
pointers to zero or more witness tables in one structure, whereas the container 
for a generic parameter only includes the value storage — the witness tables 
are stored separately so that they can be shared between all variables of the 
same type in the generic function. 



If you want to learn more about how the generics system works. Swift compiier 
deveiopers Siava Pestov and John McCail gave a talk on this topic at the 2017 LLVM 
Developers’ Meeting. We highly recommend that you watch it. 


Generic Specialization 

The compile-once-and-dispatch-dynamically model we described in the previous 
section was an important design goal for Swift’s generics system. Compared to how C++ 
templates work — where the compiler generates a separate instance of the templated 
function or class for every permutation of concrete types using the template — this leads 
to faster compilation times and potentially smaller binaries. Swift’s model is also more 
flexlhle because, unlike C++, code that uses a generic API doesn’t need to see the 
implementation of the generic function or type, only the declaration. 

The downside is lower performance at runtime, caused hy the indirection the code has 
to go through. This is likely negligible when you consider a single function call, but it 
does add up when generics are as pervasive as they are in Swift. The standard library 
uses generics everywhere, including for very common operations that must be as fast as 
possible, such as comparing values. Even if generic code is only slightly slower than 
non-generic code, chances are developers will try to avoid using it. 

Luckily, the Swift compiler can make use of an optimization called generic specialization 
to remove the overhead. Generic specialization means that the compiler clones a generic 
type or function, such as min<T>, for a concrete parameter type, such as Int. This 
specialized function can then be optimized specifically for I nt, removing all indirection. 
So the specialized version of min<T> for Int would look like this: 

func min(_ x: Int, _ y: Int) -> Int { 
return y<x?y:x 

} 

This is exactly the implementation you’d write for a concrete, non-generic min function. 
Generic specialization not only eliminates the cost of the virtual dispatch, but it also 
enables further optimizations, such as inlining, for which the indirection would 
otherwise be a barrier. 

The optimizer uses heuristics to decide which generic types or functions it chooses to 
specialize, and for which concrete types it performs the specialization. This decision 
requires a balancing of compilation times, binary size, and runtime performance. If your 
code calls min with Int arguments very frequently, but only once with Float arguments. 



chances are only the Int variant will be specialized. Make sure to compile your release 
builds with optimizations enabled (swiftc -0 on the command line) to take advantage of 
all available heuristics. 


Regardless of how aggressive the compiler is with generic specialization, the generic 
version of the function will always exist, at least if the generic function is visible to other 
modules. This ensures that external code can always call the generic version, even if the 
compiler didn’t know anything about the external types when it compiled the generic 
function. 


Whole Module Optimization 

Generic specialization only works if the compiler can see the full definition of the 
generic type or function it wants to specialize. Since Swift compiles source files 
individually by default, it can only perform specialization if the code that uses the 
generic code resides in the same file as the generic code. 

Since this is a pretty big limitation, the compiler has a flag to enable whole module 
optimization. In this mode, all files in the current module are optimized together as if 
they were one file, allowing generic specializations across the full codebase. You can 
enable whole module optimization by passing -whoie-module-optimization to swiftc. Be 
sure to do so in release builds (and possibly also in debug builds), because the 
performance gains can be huge. The drawback is longer compilation times. 


Whole module optimization enables other important optimizations. For 
example, the optimizer will recognize when an internal class has no subclasses 
in the entire module. Since the internal modifier makes sure the class isn’t 
visible outside the module, this means the compiler can replace dynamic 
dispatch with static dispatch for all methods of this class. 


Generic specialization requires the definition of the generic type or function to be 
visible, and therefore can’t be performed across module boundaries. This means your 
generic code will likely be faster for clients that reside in the same module where the 
code is defined than for external clients. The only exception to this is generic code in the 
standard library. Because the standard library is so important and used by every other 
module, definitions in the standard library are visible in all modules and thus available 
for specialization. 



Swift includes an unofficial attribute called @_specialize that allows you to make 
specialized versions of your generic code available to other modules. You must specify 
the list of types you want to specialize, so this only helps if you know your code will 
mostly be used with a limited number of types. Making specialized versions of our min 
function for integers and strings available to other modules would look like this: 

@_specialize(exported: true, where! == Int) 

@_specialize(exported: true, where! == String) 
public func mint!: Comparable>(_ x:!, _ y:!) -> ! { 
return y<x?y:x 

} 

Notice we made the function public — it makes no sense to specify @_specialize for 
internal, fileprivate, or private APIs, since those are not visible outside the module 
anyway. 

The similar (and equally unsupported) @_inlineable attribute instructs the compiler to 
make the bodies of annotated functions available to the optimizer when building client 
code. This effectively removes the cross-module optimization barrier that would 
otherwise exist. The advantage @_inlineable has over @_specialize is that the 
originating module doesn’t have to hardcode the list of concrete types because the 
specialization is performed when the client module is compiled. 

The standard library uses @_inlineable extensively. The Swift team would like to make it 
a n officially supported attribute (likely with the non-underscored name @inlinable) in 
the future. 


Recap 

In the beginning of this chapter, we defined generic programming as identifying the 
essential interface an algorithm or data type requires. We achieved this for our isSubset 
method by starting with a non-generic version and then carefully removing constraints. 
Writing multiple overloads with different constraints allowed us to provide the function 
to the widest possible range of types and meet performance expectations at the same 
time, and we relied on the compiler to select the best variant for the types involved. 

In the asynchronous networking example, we removed many assumptions about the 
network stack from our Resource struct. Concrete resource values make no assumptions 
about the server’s root domain or how to load data — they’re just inert representations 




of API endpoints. Here, generic programming heips keep the resources simpie and 
decoupied from the networking code. This aiso makes testing easier. 

If you’re interested in the theoretical details behind generic programming and how 
different languages facilitate it, we recommend Ronald Garcia et al.’s 2007 paper titled 
“ An Extended Comparative Study of Language Support for Generic Programming .” 

Finally, generic programming in Swift wouldn’t be possible without protocols. This 
brings us to our next chapter. 



Protocols 




In previous chapters, we saw how functions and generics can heip us write very dynamic 
programs. Protocois work together with functions and generics to enabie even more 
dynamic behavior. 

Swift protocois aren’t unlike Objective-C protocois. They can be used for delegation, and 
they aiiow you to specify abstract interfaces (such as IteratorProtocol or Sequence). Yet, 
at the same time, they’re very different from Objective-C protocois. For exampie, we can 
make structs and enums conform to protocols. Additionally, protocols can have 
associated types. We can even add method impiementations to protocois using protocoi 
extensions. We’ii iook at aii these things in the section on protocol-oriented 
programming. 

Protocols allow for dynamic dispatch: the correct method implementation is seiected at 
runtime based on the type of the receiver. However, when a method is or isn’t 
dynamicaily dispatched is sometimes unintuitive, and this can iead to surprising 
behavior. We’ii look at this issue in the next section. 

Reguiar protocois can be used either as type constraints or as standaione types. 

Protocols with associated types and protocois with Self requirements, however, are 
special: we can’t use them as standalone types, so something iike let x: Equatable isn’t 
aiiowed; we can oniy use them as type constraints, such as func f<T: Equatable>(x: T). 

This may sound like a smaii iimitation, but it makes protocois with associated types 
aimost entirety different things in practice. We’ii take a closer look at this iater. We’ii 
also discuss type erasers (such as Anylterator) as a way of making it easier to work with 
protocols with associated types. 

In object-oriented programming, subciassing is a powerful way to share code among 
multiple classes. A subclass inherits all the methods from its superclass and can choose 
to override some of the methods. For example, we could have an AbstractSequence class 
and subclasses such as Array and Dictionary. Doing so allows us to add methods to 
AbstractSequence, and all the subclasses would automatically inherit those methods. 

Yet in Swift, the code sharing in Sequence is implemented using protocols and protocol 
extensions. In this way, the Sequence protocol and its extensions also work with value 
types, such as structs and enums, which don’t support subclassing. 

Not relying on subclassing also makes types more flexible. In Swift (as in most other 
object-oriented languages), a class can only have a single superclass. When we create a 
class, we have to choose the superclass well, because we can only pick one; we can’t 
subclass both AbstractSequence, and, say. Stream. This can sometimes be a problem. 
There are examples in Cocoa — e.g. with NSMutableAttributedString, where the 



designers had to choose between NSAttributedString and NSMutableString as a 
superclass. 

Some languages have multiple inheritance, the most common being C++. But this leads 
to something called the “ diamond problem .” For example, if multiple Inheritance were 
possible, we could envision an NSMutableAttributedString that inherits from both 
NSMutableString and NSAttributedString. But what happens if both of those classes 
override a method of NSString? You could deal with it by just picking one of the methods. 
But what if that method is isEqual:? Providing good behavior for multiple inheritance is 
really hard. 

Because multiple inheritance is so complicated, most languages don’t support it. Yet 
many languages do support conforming to multiple protocols, which doesn’t have the 
same problems. In Swift, we can conform to multiple protocols, and the compiler warns 
us when the use of a method is ambiguous. 

Protocol extensions are a way of sharing code without sharing base classes. Protocols 
dehne a minimal viable set of methods for a type to implement. Extensions can then 
build on these minimal methods to implement more complex features. 

For example, to implement a generic algorithm that sorts any sequence, you need two 
things. First, you need a way to iterate over the elements. Second, you need to he able to 
compare the elements. That’s it. There are no demands as to how the elements are held. 
They could he in a linked list, an array, or any iterable container. What they are doesn’t 
matter, either — they could be strings. Integers, dates, or people. As long as you write 
down the two aforementioned constraints in the type system, you can Implement sort: 

extension Sequence where Element: Comparable { 
func sortedO -> [Element] 

} 

To implement an in-place sort, you need more building blocks. More specihcally, you 
need index-based access to the elements rather than just linear iteration. Collection 
captures this and MutableCollection adds mutation to it. Finally, you need to compare 
and offset indices in constant time. RandomAccessCollection allows for that. This may 
sound complex, but it captures the prerequisites needed to perform an in-place sort: 

extension MutableCollection where 
Self: RandomAccessCollection, Element: Comparable { 
mutating func sort() 

} 



Minimal capabilities described by protocols compose well. You can add different 
capabilities of different protocols to a type, bit by bit. We saw this in the collection 
protocols chapter when we first built a List type by giving it a single method, cons. 
Without changing the original List struct, we made it conform to Sequence. In fact, we 
could’ve done this even if we weren’t the original authors of this type, using a technique 
called retroactive modeling. By adding conformance to Sequence, we get all the 
extension methods of Sequence for free. 

Adding new shared features via a common superclass isn’t this flexible. You can’t just 
decide later to add a new common base class to many different classes; that would be a 
major refactoring. And if you aren’t the owner of these subclasses, you can’t do it at all! 

Subclasses have to know which methods they can override without breaking the 
superclass. For example, when a method is overridden, a subclass might need to call the 
superclass method at the right moment: either at the beginning, somewhere in the 
middle, or at the end of the method. This moment is often unspecified. Also, by 
overriding the wrong method, a subclass might break the superclass without warning. 


Protocol-Oriented Programming 

In a graphical application, we might want different render targets: for example, we can 
either render graphics in a Core Graphics CGContext or create an SVG file. To start, we’ll 
define a protocol that describes the minimum functionality of our drawing API: 

protocol Drawing! 

mutatingfunc addEllipse(rect:CGRect, fill: UlColor) 
mutatingfunc addRectanglefrect: CGRect,fill: UlColor) 

} 

One of the most powerful features of protocols is that we can retroactively modify any 
type to add conformance to a protocol. For CGContext, we can add an extension that 
makes it conform to the Drawing protocol: 

extension CGContext: Drawing { 
func addEllipse(rect: CGRect, fill: UlColor) { 
setFillColor(filLcgColor) 
fillEllipsefin: rect) 

} 


func addRectanglefrect: CGRect, fill fillColor: UlColor) { 


setFillColor(fiUColor.cgColor) 

fiU(rect) 

} 


To represent an SVG file, we create an SVG struct. It contains an XMLNode with children 
and has a single method, append, which appends a child node to the root node. (We’ve 
left out the dehnition of XMLNode here.) 

struct SVG { 

var rootNode = XMLNode(tag: "svg'') 

mutatingfunc append(node: XMLNode) { 
rootNode.children.append(node) 

} 

} 

Rendering into an SVG means we have to append a node for each element. We use a few 
simple extensions: the svgAttributes property on CGRect creates a dictionary that 
matches the SVG specihcation. String.init(hexColor:) takes a UlColor and turns it into a 
hexadecimal string (such as "#010100"). With these helpers, adding Drawing 
conformance is straightforward: 

extension SVG: Drawing { 

mutating func addEllipse(rect: CGRect, fill; UlColor) { 
var attributes: [String:String] = rect.svgAttributes 
attributes["fill"] = String(hexColor: fill) 

append(node: XMLNode(tag: "ellipse", attributes: attributes)) 

} 

mutating func addRectangle(rect: CGRect, fill: UlColor) { 
var attributes: [String:String] = rect.svgAttributes 
attributes["fill"] = String(hexColor: fill) 
append(node: XMLNode(tag: "rect", attributes: attributes)) 

} 


We can now write drawing code that’s Independent of the rendering target; the following 
code only assumes that our context variable conforms to the Drawing protocol. If we 
initialized context with a CGContext instead, we wouldn’t need to change any of the 
code: 


var context: Drawing = SVGQ 
let recti = CGRect(x: 0, y: 0, width: 100, height: 100) 
let rect2 = CGRect(x: 0, y: 0, width: 50, height: 50) 
context.addRectangle(rect: recti, fill: .yellow) 
context.addEllipse(rect: rect2, fill: .blue) 
context 
/* 

<svg> 

<rect cy="0.0" filt="#010100" ry=" 100.0" rx=" 100.0" cx="0.0"/> 
<elUpse cy= "0.0" fill="#000001" ry= "50.0" rx= "50.0" cx= "0.0"/> 
</svg> 

*/ 


Protocol Extensions 

Another powerful feature of Swift protocols is the possibility to extend a protocol with 
full method implementations; you can do this to both your own protocols and existing 
protocols. For example, we could add a method to Drawing that, given a center point and 
a radius, renders a circle: 

extension Drawing! 

mutatingfunc addCircle(center: CGPoint, radius: CGFloat, fill: UlColor) { 
let diameter = radius * 2 

let origin = CGPoint(x: center.x - radius, y: center.y - radius) 
let size = CGSize(width: diameter, height: diameter) 
let rect = CGRect(origin: origin, size: size) 
addEllipse(rect: rect, fill: fill) 

} 

} 

By adding addCircle in an extension, we can use it both with CGContext and our SVG 
type. 

Note that code sharing using protocols has several advantages over code sharing using 
inheritance: 


-> We’re not forced to use a specific superclass. 


-> We can conform existing types to a protocoi (e.g. we made CGContext conform to 
Drawing). Subclassing isn’t as flexible; if CGContext were a class, we couldn’t 
retroactively change its superclass. 

-> Protocols work with both structs and classes, hut structs can’t have superclasses. 

-> Finally, when dealing with protocols, we don’t have to worry about overriding 
methods or calling super at the right moment. 


Overriding Methods in Protocol Extensions 

As the author of a protocol, you have two options when you add a protocol method in an 
extension. First, you can choose to only add it in an extension, as we did above with 
addCircle. Or, you could also add the method declaration to the protocol dehnition itself, 
making the method a protocol requirement. Protocol requirements are dispatched 
dynamically, whereas methods that are only dehned in an extension use static dispatch. 
The difference is subtle but important, both as a protocol author and as a user of 
conforming types. 

Let’s look at an example. In the previous section, we added addCircle as an extension of 
the Drawing protocol, but we didn’t make it a requirement. If we want to provide a more 
specihc version of addCircle for the SVG type, we can just “override” the method: 

extension SVG { 

mutatingfunc addCircle(center: CGPoint, radius: CGFloat, fill: UlColor) { 
var attributes: [String:String] = [ 

"ex": "\(center.x)", 

"cy": "\(center.y)", 

"r":"\(radius)", 

] 

attributes[''fill"] = String(hexColor: fill) 

append(node: XMLNode(tag: "circle", attributes: attributes)) 

} 

} 

If we now create an instance of SVG and call addCircle on it, it behaves as you’d expect: 
the compiler will pick the most specific version of addCircle, which is the version that’s 
dehned in the extension on SVG. We can see that it correctly uses the circle tag: 

var sample = SVG() 

sample.addCirclefcenter: .zero, radius: 20, fill: .red) 


print(sample) 

/* 

<svg> 

Kcircle cy="0.0" fill="#010000" r="20.0" cx="0.0"/> 
</svg> 

*/ 


Now, just like above, we create another SVG instance; the only difference is that we 
explicitly cast the variable to the Drawing type. What’ll happen if we call addCircle on 
this Drawing-that’s-really-an-SVG? Most people would probably expect that this call 
would be dispatched to the same implementation on SVG, hut that’s not the case: 

var otherSample: Drawing = SVG() 

otherSample.addCircle(center: .zero, radius: 20, fill: .red) 
print(otherSamp[e) 

/* 

<svg> 

<ellipse cy="-20.0" fill="#010000" ry="40.0" rx="40.0" cx="-20.0"/> 

</svg> 

*/ 


It returned an ellipse element, and not the circle we were expecting. It turns out it used 
the addCircle method from the protocol extension and not the method from the SVG 
extension. When we defined otherSample as a variable of type Drawing, the compiler 
automatically boxed the SVG value in a type that represents the protocol. This hox is 
called an existential container, the details of which we’ll look into later in this chapter. 
For now, let’s consider the behavior: when we call addCircle on our existential container, 
the method is statically dispatched, i.e. it always uses the extension on Drawing. If it 
were dynamically dispatched, it would’ve taken the type of the receiver (SVG) into 
account. 

To make addCircle dynamically dispatched, we add it as a protocol requirement: 
protocol Drawing { 

mutatingfunc addEllipse(rect:CGRect, fill: UlColor) 

mutatingfunc addRectangle(rect: CGRect,fill: UlColor) 

mutating func addCircle(center: CGPoint, radius: CGFloat, fill: UlColor) 

} 

We can still provide a default implementation, just like before. And also like before, 
types are free to override addCircle. Because it’s now part of the protocol definition, it’ll 


be dynamically dispatched — at runtime, depending on the dynamic type of the 
receiver, the existential container will call the custom implementation if one exists. If it 
doesn’t exist, it’ll use the default implementation from the protocol extension. The 
addCircle method has become a customization point for the protocol. 

The Swift standard library uses this technique a lot. A protocol like Sequence has dozens 
of requirements, yet almost all have default implementations. A conforming type can 
customize the default implementations because the methods are dynamically 
dispatched, but it doesn’t have to. 


Two Types of Protocols 

As we stated in the introduction of this chapter, protocols with associated types are 
different from regular protocols. The same is true for protocols with a Self requirement, 
i.e. those that refer to Self anywhere in their definition. In Swift 4, these protocols can’t 
be used as standalone types. This restriction will probably be lifted in a future version 
once the full generics system is implemented, but until then, we have to deal with the 
limitations. 

One of the simplest examples of a protocol with an associated type is IteratorProtocol. It 
has a single associated type. Element, and a single function, next(), which returns an 
optional value of that type: 

public protocol IteratorProtocol { 
associatedtype Element 
public mutating func nextO -> Element? 

} 

In the chapter on collection protocols, we showed an example of a type that conforms to 
IteratorProtocol. This iterator simply returns 1 each time it’s called: 

struct Constantiterator: IteratorProtocol { 
mutating func nextQ -> lnt?{ 
return 1 

} 

} 

As we’ve seen, IteratorProtocol forms the base for the collection protocols. Unlike 
IteratorProtocol, the Collection protocol doesn’t have a simple definition: 


protocol Collection: _lndexable, Sequence { 
associatedtype IndexDistance = Int 

associatedtype Iterator: IteratorProtocol = lndexinglterator<Self> 

//... Method definitions and more associated types 

} 

Let’s look at some of the important parts of the definition above. The collection protocol 
inherits from _lndexable and Sequence. Because protocol inheritance doesn’t have the 
same problems as inheritance through subclassing, we can compose multiple protocols: 

protocol Collection: _lndexable, Sequence { 

Next up, we have two associated types: IndexDistance and Iterator. Both have a default 
value: IndexDistance is just an Int, and Iterator is an Indexingiterator. Note that we can 
use Self for the generic type parameter of Indexingiterator. Both types also have 
constraints: IndexDistance needs to conform to the Signedinteger protocol (this is 
defined in_lndexable), and Iterator needs to conform to IteratorProtocol (this is defined 
in Sequence): 

associatedtype IndexDistance: Signedinteger = Int 
associatedtype Iterator: IteratorProtocol = lndexinglterator<Self> 

There are two options when we make our own types conform to the Collection protocol. 
We can either use the default associated types, or we can assign our own associated 
types (for example, in the collection protocols chapter, we made Words have a custom 
associated type for Subsequence), if we decide to stick with the default associated types, 
we get a lot of functionality for free. For example, there’s a conditional protocol 
extension that adds an implementation of makelteratorO when the Iterator type isn’t 
overridden: 

extension Collection where Iterator == lndexinglterator<Self> { 
func makelteratorO -> lndexinglterator<Self> 

} 

There are many more conditional extensions, and you can also add your own. As we 
mentioned earlier, it can be challenging to see which methods you should implement in 
order to conform to a protocol. Because many protocols in the standard library have 
default values for the associated types and conditional extensions that match those 
associated types, you often only have to implement a handful of methods, even for 
protocols that have dozens of requirements. The (small) downside is that it can be 
difficult to determine what the minimal set of methods is that a conforming type has to 


implement to make the compiler happy. To address this, the standard library has 
documented it in a section, “Conforming to the Collection Protocol.” If you write a 
custom protocol with more than a few methods, you should consider adding a similar 
section to your documentation. 


Type Erasers 

In the previous section, we were able to use the Drawing protocol as a type. However, 
with IteratorProtocol, this isn’t (yet) possible, because it has an associated type. The 
compile error says: “Protocol ‘IteratorProtocol’ can only be used as a generic constraint 
because it has Self or associated type requirements.” 

let iterator: IteratorProtocol = ConstantlteratorQ Error 

In a way, IteratorProtocol is an incomplete type; we’d have to specify the associated type 
as well in order for this to be meaningful. 


The Swift Core Team has stated that they want to support generalized 
existentials. This feature would allow for using protocols with associated 
types as standalone values, and it would also eliminate the need to write type 
erasers. For more information about what to expect in the future, see the Swift 
Generics Manifesto. 


In a future version of Swift, we might be able to solve this by saying something like the 
following: 

let iterator: Any<lteratorProtocol where .Element == lnt> = ConstantlteratorQ 

Currently, we can’t yet express this. We can, however, use IteratorProtocol as a constraint 
for a generic parameter: 

func nextlnt<l: lteratorProtocol>(iterator: inout I) -> Int? 
where I.Element == Int { 
return iterator.nextO 

} 

Similarly, we can store an iterator in a class or struct. The limitation is the same, in that 
we can only use it as a generic constraint, and not as a standalone type: 





class lteratorStore<l: lteratorProtocol> where I.Element == Int { 
var iterator: I 

init(iterator: I) { 
self.iterator = iterator 

} 

} 

This works, but it has a drawback: the specihc type of the stored iterator “leaks out” 
through the generic parameter. In the current type system, we can’t express “any 
iterator, as long as the element type is i nt.” This is a problem if you want to, for example, 
put multiple iteratorStores into an array. All elements in an array must have the same 
type, and that includes any generic parameters; it’s not possible to create an array that 
can store both lteratorStore<Constantlterator> and lteratorStore<Fibsiterator>. 

Luckily, there are two ways around this — one is easy, the other one more efficient (but 
hacky). The process of removing a specihc type (such as the iterator) is called type 
erasure. 

In the easy solution, we implement a wrapper class. Instead of storing the iterator 
directly, the class stores the iterator’s next function. To do this, we must hrst copy the 
iterator parameter to a local var variable so that we’re allowed to call its next method 
(which is mutating). We then wrap the call to next() in a closure expression and assign 
that closure to a property. We used a class to signal that Intiterator has reference 
semantics: 

class Intiterator { 
var nextlmpl: () -> Int? 

init<l: lteratorProtocol>(_ iterator: I) where I.Element == Int { 
var iteratorCopy = iterator 
self.nextlmpl = {iteratorCopy.nextQ} 

} 

} 

Now, in our Intiterator, the concrete type of the iterator (e.g. Constantiterator) is only 
specihed when creating an instance. After that, the concrete type is hidden, captured by 
the closure. We can create an Intiterator with any kind of iterator, as long as the elements 
are integers: 


var iter = lntlterator(Constantlterator()) 


iter = lntlterator([1,2,3].makelterator()) 


The code above allows us to specify the associated type constraints (e.g. iter contains an 
iterator with Int elements) using Swift’s current type system. Our Intiterator can also 
easily conform to the IteratorProtocoi (and the inferred associated type is Int): 

extension Intiterator: IteratorProtocoi { 
func nextO -> lnt?{ 
return nextlmplO 

} 

} 

In fact, by abstracting over Int and adding a generic parameter for the iterator’s element 
type, we can change Intiterator to work just like the standard library’s Anylterator does: 

class Anylterator<A>: IteratorProtocoi { 
var nextlmpl: () -> A? 

init<l: lteratorProtocol>(_ iterator: I) where I.Element == A { 
var iteratorCopy = iterator 
self.nextlmpl = {iteratorCopy.nextQ} 

} 

func nextO -> A?{ 
return nextlmplO 

} 

} 

The concrete iterator type (I) is only specihed in the initializer, and after that, it’s 
“erased.” 

From this refactoring, we can come up with a simple algorithm for creating a type eraser. 
First, we create a struct or class named AnyProtocolName. Then, for each associated 
type, we add a generic parameter. Next, for each of the protocol’s methods, we store the 
implementation in a property on AnyProtocolName. Finally, we write an initializer that’s 
generic over the concrete type we want to erase; its task is to capture the object that’s 
passed in in closures that get assigned to the properties. 

For a simple protocol like IteratorProtocoi, this only takes a few lines of code, but for 
more complex protocols (such as Sequence), this is quite a lot of work. Even worse, the 


size of the object or struct will increase linearly with each protocol method (because a 
new property is added for each method). 

The standard library takes a different approach to erasing types: it uses a class hierarchy 
to hide the concrete iterator type in a subclass, while the client-facing base class is only 
generic over the element type. 

To see how this works, we start hy creating a simple abstract class that conforms to 
IteratorProtocol. Its generic type is the Element of the iterator, and the implementation 
will simply crash: 

class lteratorBox<Element>: IteratorProtocol { 
func nextO -> Element? { 
fatalErrorC'This method is abstract.") 

} 

} 

Then, we create another class, IteratorBoxHelper, which is also generic. Here, the generic 
parameter is the specihc iterator type (for example, Constantiterator). The purpose of 
this class is to store the underlying iterator in a property. The next method simply 
forwards to the iterator’s next method: 

class IteratorBoxHelpertI: lteratorProtocol> { 
var iterator: I 
init(iterator: I) { 
self.iterator = iterator 

} 

func nextO -> I.Element?! 
return iterator.nextO 

} 

} 

Now for the hacky part. We change IteratorBoxHelper so that it’s a subclass of 
IteratorBox, and the two generic parameters are constrained in such a way that 
IteratorBox gets I’s element as the generic parameter: 

class IteratorBoxHelpertI: lteratorProtocol>: lteratorBox<I.Element> { 
var iterator: I 
init(_ iterator: I) { 
self.iterator = iterator 


} 


override func next() -> I. Element? { 
return iterator.nextO 

} 

} 

The “magic” happens in the initializer of IteratorBoxHelper. IteratorBox can’t have a 
property to store the wrapped iterator directly, because then it would need to be generic 
over the concrete iterator type, which is exactly what we want to avoid. The solution is to 
hide this property (and with it, its concrete type) in the subclass, which can be generic 
over the concrete iterator type. IteratorBox is then able to be generic only over the 
element type. 

This allows us to create a value of IteratorBoxHelper and use it as an IteratorBox, 
effectively erasing the type of I: 

let iter: lteratorBox<lnt> = lteratorBoxHelper(Constantlterator()) 

In the standard library, the IteratorBox and IteratorBoxHelper are then made private, and 
yet another wrapper (Anylterator) makes sure that these implementation details are 
hidden from the public interface. 


Protocols with Self Requirements 

Protocols with Self requirements behave in a way similar to protocols with associated 
types. One of the simplest protocols with a Self requirement is Equatable. It has a single 
method (in the form of an operator) that compares two elements: 

protocol Equatable { 
static func = = (lhs: Self, rhs: Self) -> Bool 

} 

Implementing Equatable for your own type isn’t too hard. For example, if we have a 
simple MonetaryAmount struct, we can compare two values by comparing their 
properties: 

struct MonetaryAmount: Equatable { 
var currency: String 


var amountInCents: Int 


static func = = (lhs: MonetaryAmount, rhs: MonetaryAmount) -> Bool { 
return Ihs.currency == rhs.currency && 

ths.amountInCents == rhs.amountInCents 

} 

} 

We can’t simply declare a variable with Equatable as its type: 

//Error: 'Equatable' can only be used as a generic constraint 

// because it has Self or associated type requirements 

let x: Equatable = MonetaryAmount(currency: ''EUR'', amountInCents: 100) 

This suffers from the same problems as associated types: from this (incorrect) 
declaration, it’s unclear what the Self type should be. For example, if it were possible to 
use Equatable as a standalone type, you could also write this: 

let x: Equatable = MonetaryAmount(currency: "EUR", amountInCents: 100) 

let y: Equatable = "hello" 

x==y 

There’s no definition of == that takes a monetary amount and a string. How would you 
compare the two? However, we can use Equatable as a generic constraint. For example, 
we could write a free function, allEqual, that checks whether all elements in an array are 
equal: 

func allEquaUE: Equatable>(x: [E]) -> Bool { 
guard let firstElement = x.first else { return true } 
for element in x { 

guard element == firstElement else { return false} 

} 

return true 

} 

Or we could use it as a constraint when writing an extension on Collection: 

extension Collection where Element: Equatable { 
func allEqualO -> Bool { 

guard let firstElement = first else { return true } 
for element in self { 


guard element == firstElement else { return false} 

} 

return true 

} 

} 

The = = operator is defined as a static function of the type. In other words, it’s not a 
member function, and it’s statically dispatched. Unlike member functions, we can’t 
override it. If you have a class that Implements Equatable (for example, NSObject), you 
might get unexpected behavior when you create a subclass. For example, consider the 
following class: 

class IntegerRef: NSObject { 
let int: Int 
init(_ int: Int) { 
self, int = int 

} 

} 

We can define aversion of = = that compares two IntegerRefs by comparing their int 
properties: 

func = = (lhs: IntegerRef, rhs: IntegerRef) -> Bool { 
return lbs.int == rhs.int 

} 

If we create two IntegerRef objects, we can compare them, and everything works as 
expected: 

let one = IntegerRef(l) 
let otherOne = IntegerRef(l) 
one == otherOne//true 

However, if we use them as NSObjects, the == of NSObject is used (which uses === 
under the hood to check if the references point to the same object). Unless you’re aware 
of the static dispatch behavior, the result might come as a surprise: 

let two: NSObject = lntegerRef(2) 
let otherTwo: NSObject = lntegerRef(2) 
two == otherTwo/'fo/se 


Protocol Internals 


As we mentioned earlier, when we create a variable that has a protocol type, it’s wrapped 
in a box called an existential container. Let’s take a closer look at this. 

Consider the following pair of functions. Both take a value that conforms to 
CustomStringConvertible and return the size of the value’s type. The only difference is 
that one function uses the protocol as a generic constraint, whereas the other uses it as a 
type: 

func f<C: CustomStringConvertible>L x: C) -> Int { 
return MemoryLayout.sizefofValue: x) 

} 

func g(_ x: CustomStringConvertible) -> Int { 
return MemoryLayout.sizefofValue: x) 

} 

f(5)//S 

g(5)//40 

Where does the size difference of 8 bytes versus 40 bytes come from? Because f takes a 
generic parameter, the integer 5 is passed straight to the function without any kind of 
boxing. This is reflected in its size of 8 bytes, which is the size of Int on a 64-bit system. 
For g, the integer is wrapped in an existential container. For regular 
(l.e. non-class-constrained) protocols, an opaque existential container is used. Opaque 
existential containers contain a buffer (the size of three pointers, or 24 bytes) for the 
value; some metadata (one pointer, 8 bytes); and a number of witness tables (zero or 
more pointers, 8 bytes each). If the value doesn’t fit into the buffer, it’s stored on the 
heap, and the buffer contains a reference to the storage location. The metadata contains 
information about the type (so that it can be used with a conditional cast, for example). 

The witness table is what makes dynamic dispatch possible. It encodes the 
implementation of a protocol for a specific type: for each method in the protocol, the 
table contains an entry that points to the implementation for that specific type. 
Sometimes this is also called a viable. In a way, when we created the first version of 
Anylterator, we manually wrote a witness table. 

Given the witness table, the surprising behavior of addCircle at the beginning of this 
chapter makes a lot more sense. Because addCircle wasn’t part of the protocol definition 
(i.e. it wasn’t a requirement), it wasn’t in the witness table either. Therefore, the compiler 
had no choice but to statically call the protocol’s default Implementation. Once we made 


addCircle a protocol requirement, it was also added to the witness table, and therefore 
called using dynamic dispatch. 

The size of the opaque existential container depends on the number of witness tables: it 
contains one witness table per protocol. For example. Any is a typealias for an empty 
protocol that has no witness tables at all: 

typealias Any = protocolO 

Memory Layout<Any>. size 32 

If we combine multiple protocols, one 8-byte chunk gets added per protocol. So 
combining four protocols adds 32 bytes: 

protocol Prot {} 
protocol Prot2 {} 
protocol Prot3 {} 
protocol Prot4 {} 

typealias P = Prot & Prot2 & Prot3 & Prot4 
Memory Layout<P>.size 64 

For class-only protocols, there’s a special existential container called a class existential 
container, which only has the size of two words (plus one word per additional witness 
table) — one for the metadata and one (Instead of three) for a reference to the class: 

protocol ClassOnly: AnyObject {} 

MemoryLayout<Class0nly>.size/7 76 

Objective-C protocols that get imported into Swift don’t have additional metadata. 
Therefore, variables whose type is an Objective-C protocol don’t have to be wrapped in 
an existential container; they only consist of a plain pointer to their class: 

MemoryLayout<NSObjectProtocol>.size 4^8 


Performance Implications 

Existential containers add a level of indirection and therefore generally cause a 
performance decrease over generic parameters (assuming the compiler can specialize 
the generic code). In addition to the possibly slower method dispatch, the existential 
container also acts as a barrier that prevents many compiler optimizations. For the most 


part, worrying about this overhead is premature optimization. However, if you need 
maximum performance in a tight loop, it’ll he more efficient to use a generic parameter 
rather than a parameter that has a protocol type. This way, you can avoid the implicit 
protocol box. 

If you try to pass [String] (or any other type) into a function that takes [Any] (or any other 
array of a protocol rather than a specific type), the compiler will emit code that maps 
over the entire array and boxes every value, effectively making the function call itself — 
not the function body — an 0(n) operation (where n is the number of elements in the 
array). Again, this won’t he an issue in most cases, but if you need to write highly 
performant code, you might choose to write your function with a generic parameter 
rather than a protocol type: 

//Implicit boxing 

func printProtocol(array: [CustomStringConvertible]) { 
print(array) 

} 

//No boxing 

func printGeneric<A: CustomStringConvertib[e>(array: [A]) { 
print(array) 

} 


Recap 

Protocols in Swift are important building blocks. They allow us to write flexible code 
that decouples the interface and implementation. We looked at the two different kinds 
of protocols and how they’re implemented. We used type erasers and looked at the 
performance differences between protocol types and generic types with a protocol 
constraint. We also looked at unexpected behavior due to the differences between static 
and dynamic dispatch. 

Protocols had a big impact on the Swift community. Yet we also want to warn against 
overusing them. Sometimes, using a simple concrete type like a struct or a class Is much 
easier to understand than a protocol, and this increases the readability of your code. 
However, there are also times when using a protocol can Increase readability of your 
code — for example, when you deal with legacy APIs retrofitted to a protocol. 

One of the big upsides of using protocols is that they provide a minimal viable Interface; 
a well-designed protocol specifies the minimum set of requirements conforming types 


must meet to be able to work with algorithms that were designed for the protocol. Also, 
protocols can make it easier to write test code. Rather than having to set up a 
complicated tree of dependencies, we can just create a simple test type that conforms to 
the protocol. 



Interoperability 




One of Swift’s greatest strengths is the iow friction when interoperating with C and 
Objective-C. Swift can automaticaliy bridge Objective-C types to native Swift types, and 
it can even bridge with many C types. This aiiows us to use existing iibraries and provide 
a nice interface on top. 

In this chapter, we’li create a wrapper around the CommonMark library. CommonMark 
is a formal specihcation for Markdown, a popular syntax for formatting plain text. If 
you’ve ever written a post on GitHub or Stack Overflow, you’ve probably used Markdown. 
After this practical example, we’ll take a look at the tools the standard library provides 
for working with memory, and we’ll see how they can be used to interact with C code. 


Hands-On: Wrapping CommonMark 

Swift’s ability to call into C code allows us to take advantage of the abundance of existing 
C libraries. Writing a wrapper around an existing library’s interface in Swift is often 
much easier and involves less work than building something from scratch; meanwhile, 
users of our wrapper will see no difference in terms of type safety or ease of use 
compared to a fully native solution. All we need to start is the dynamic library and its C 
header hies. 

Our example, the CommonMark C library, is a reference implementation of the 
CommonMark spec that’s both fast and well tested. We’ll take a layered approach in 
order to make CommonMark accessible from Swift. First, we’ll create a very thin Swift 
class around the opaque types the library exposes. Then, we’ll wrap this class with Swift 
enums in order to provide a more idiomatic API. 


Setup 

Setting up a C library so that it can be imported from a Swift project is a little 
complicated. Here’s a quick rundown of the required steps. 

The first step is to install the cmark library . We use Homebrew as our package manager 
on macOS to do this: 

$ brew install cmark 


At the time of writing, cmark 0.28.2 was the most recent version. 





In C, you’d now #include one or more of the library’s header files to make their 
declarations visible to your own code. Swift can’t handle C header files directly; it 
expects dependencies to be modules. For a C or Objective-C library to be visible to the 
Swift compiler, the library must provide a module map in the Clang modules format. 
Among other things, the module map lists the header files that make up the module. 

Since cmark doesn’t come with a module map, your next task is to make one. You’ll 
create a package for the Swift Package Manager that won’t contain any code; its only 
purpose is to act as the module wrapper for the cmark library. 

Create a directory for the package and then call swift package init, telling the package 
manager to create the scaffolding for a system module: 

$ mkdir Ccmark 
$ cd Ccmark 

$ swift package init --type system-module 

In SwiftPM lingo, system packages are libraries installed by systemwide package 
managers, such as Homebrew, or APT on Linux. A system module is any SwiftPM 
package that refers to such a library. By convention, the names of pure wrapper modules 
such as this should be prefixed with C. 

Edit Package.swift to look like this: 

// swift-tools-versionA.O 
import PackageDescription 

let package = Package( 
name: "Ccmark", 
pkgConfig: "libcmark", 
providers: [ 

.brew(["cmark'']) 

] 

) 


The pkgConfig parameter specifies the name of the config file where the package 
manager can find the header and library search paths for the imported library. The 
providers directive is optional. It’s an installation hint the package manager can display 
when the target library isn’t installed. 




Before you edit the module map, create a C header file named shim.h. It should contain 
only the following line: 

#include <cmark.h> 

Finally, the module.modulemap file should look like this: 

module Ccmark [system] { 
header ''shim.h'' 
link "cmark" 
export * 

} 

The shim header works around the limitation that module maps must contain absolute 
paths. Alternatively, you could’ve omitted the shim and specified the cmark header 
directly in the module map, as in header "/usr/local/include/cmark.h''. But then the path 
of cmark. h would be hardcoded into the module map. With the shim, the package 
manager reads the correct header search path from the pkg-config file and adds it to the 
compiler invocation. 

The final step for the Ccmark package is to commit everything to a Git repository: 

$ git init 
$ git add . 

$ git commit -m "initial commit" 

This is necessary because you’ll now create a second package which imports Ccmark, 
and the package manager requires a Git branch or tag name for each dependency. 

Create another directory next to the Ccmark directory and call swift package init once 
more, this time for an executable: 

$ cd .. 

$ mkdir CommonMarkExample 
$ cd CommonMarkExample 
$ swift package init --type executable 

You’ll need to add the Ccmark dependency to the package manifest: 


// swift-tools-version'A.O 


import PackageDescription 


let package = Package( 
name: "CommonMarkExample", 
dependencies: [ 

.package(url: "../Ccmark", .branchC'master")), 

], 

targets: [ 

.target( 

name: "CommonMarkExample", 
dependencies: []), 

] 

) 


Notice that we’re using a relative file system path to refer to Ccmark. If you want to make 
this accessible to other team members, push the Ccmark repository to a server and 
replace its URL here. 

Now you should be able to import Ccmark and call any cmark API. Add the following 
snippet to main.swift for a quick test to see if everything works: 

import Ccmark 

let markdown = "*Hello World*" 

let cString = cmark_markdown_to_html(markdown, markdown.utf8.count, 0)! 

let html = String(cString: cString) 

print(html) 

Back in Terminal, run the program: 

$ swift run 

If you see <p><em>HeUo World</em></p> as the output, you just successfully called a C 
function from Swift! Now that we have a working installation, we can start writing our 
Swift wrapper. 


Wrapping the C Library 


Let’s begin by wrapping a singie function with a nicer interface. The 
cmark_markdown_to_html function takes in Markdown-formatted text and returns the 
resuiting HTML code in a string. The C interface iooks iike this: 

///Convert 'text' (assumed to be a UTF-8 encoded string with length 

/// 'len') from CommonMark Markdown to HTML, returning a null-terminated, 

/// UTF-8-encoded string. It is the caller's responsibility 
///to free the returned buffer. 

char *cmark_markclown_to_html(const char *text, size_t len, int options); 

When Swift imports this deciaration, it presents the C string in the first parameter as an 
UnsafePointer to a number of IntS vaiues. From the documentation, we know that these 
are expected to be UTF-8 code units. The len parameter takes the length of the string: 

//The function's interface in Swift 
func cmark_markdown_to_html 
(_ text: UnsafePointer<lnt8>!, _ len: Int, _ options: Int32) 

-> UnsafeMutablePointer<lnt8>! 

We want our wrapper function to work with Swift strings, of course, so you might think 
that we need to convert the Swift string into an IntS pointer before passing it to 
cmark_markdown_to_html. However, bridging between native and C strings is such a 
common operation that Swift will do this automatically. We do have to be careful with 
the len parameter, as the function expects the length of the UTF-8-encoded string in 
bytes, and not the number of characters. We get the correct value from the string’s utf8 
view, and we can just pass in zero for the options: 

func markdownToHtml(input: String) -> String { 
let outString = cmark_markdown_to_html(input, input.utf8.count, 0)! 
defer {free(outString)} 
return String(cString: outString) 

} 

Notice that we force-unwrap the string pointer the function returns. We can safely do 
this because we know that cmark_markdown_to_html always returns a valid string. By 
force-unwrapping inside the method, the library user can call the markdownToHtml 
method without having to worry about optionals — the result would never be nil anyway. 
This is something the compiler can’t do automatically for us — C and Objective-C 


pointers without nuiiabiiity annotations are aiways imported into Swift as impiicitiy 
unwrapped optionais. 


The automatic bridging of native Swift strings to C strings assumes that the C 
function you want to caii expects the string to be UTF-8 encoded. This is the 
correct choice in most cases, but if the C API assumes a different encoding, you 
can’t use the automatic bridging. However, it’s often quite easy to construct 
aiternative formats. For exampie, if the C API expects an array of UTF-16 code 
points, you can use Array(string.utf16). The Swift compiier wiii automaticaliy 
bridge the Swift array to the expected C array, provided that the eiement types 
match. 


Wrapping the cmark_node Type 

In addition to the straight HTML output, the cmark iibrary aiso provides a way to parse a 
Markdown text into a structured tree of elements. For example, a simple text could be 
transformed into a list of block-level nodes such as paragraphs, quotes, lists, code blocks, 
headers, and so on. Some block-level elements contain other block-level elements (for 
example, quotes can contain multiple paragraphs), whereas others contain only inline 
elements (for example, a header can contain a part that’s emphasized). No element can 
contain both (for example, the inline elements of a list item are always wrapped in a 
paragraph element). 

The C library uses a single data type, cmark_node, to represent the nodes. It’s opaque, 
meaning the authors of the library chose to hide its definition. All we see in the headers 
are functions that operate on or return pointers to cmark_node. Swift imports these 
pointers as OpaquePointers. (We’ll take a closer look at the differences between the many 
pointer types in the standard library, such as OpaquePointer and UnsafeMutablePointer, 
later in this chapter.) 


In the future, we might be able to use the “ import as member” feature of 
Swift to import these functions as methods on cmark_node. Apple has used 
this to provide more “object-oriented” APIs for Core Graphics and Grand 
Central Dispatch in Swift. It works by annotating the C source code with the 
swift_name attribute. Alas, this feature doesn’t really work for the cmark 
library yet. It might work for your own C library. There are some bugs around 






import as member, for example, it doesn’t always work with opaque pointers 
(which is exactly what’s used in cmark). 


Let’s wrap a node in a native Swift type to make it easier to work with. As we saw in the 
chapter on structs and classes, we need to think about value semantics whenever we 
create a custom type: is the type a value, or does it make sense for instances to have 
identity? In the former case, we should favor a struct or enum, whereas the latter 
requires a class. Our case is interesting: on one hand, the node of a Markdown 
document is a value — two nodes that have the same element type and contents should 
be indistinguishable, hence they shouldn’t have identity. On the other hand, since we 
don’t know the internals of cmark_node, there’s no straightforward way to make a copy 
of a node, so we can’t guarantee value semantics. For this reason, we start with a class. 
Later on, we’ll write another layer on top of this class to provide an Interface with value 
semantics. 

Our class simply stores the opaque pointer and frees the memory cmark_node uses on 
deinit when there are no references left to an instance of this class. We only free memory 
at the document level, because otherwise we might free nodes that are still in use. 
Freeing the document will also automatically free all the children recursively. Wrapping 
the opaque pointer in this way will give us automatic reference counting for free: 

public class Node { 
let node: OpaquePointer 

init(node: OpaquePointer) { 
self.node = node 

} 

deinit { 

guard type == CMARK_NODE_DOCUMENT else { return } 
cmark_node_free(node) 

} 

} 

The next step is to wrap the cmark_parse_document function, which parses a Markdown 
text and returns the document’s root node. It takes the same arguments as 
cmark_markdown_to_html: the string, its length, and an integer describing parse 
options. The return type of the cmark_parse_document function in Swift is 
OpaquePointer, which represents the node: 


func cmark_parse_document 
(_ buffer: UnsafePointer<lnt8>!, _ len: Inf, _ options: Int32) 

-> OpaquePointer! 

We turn the function into an initiaiizer for our class. Note that the function can return 
nil if parsing fails. Therefore, our initializer should be failable and return nil (the 
optional value, not the null pointer) if this occurs: 

public init?(markdown: String) { 
guard let node = cmark_parse_document(markdown, 
markdown.utf8.count, 0) else { return nil } 
self.node = node 

} 

As mentioned above, there are a couple of interesting functions that operate on nodes. 
For example, there’s one that returns the type of a node, such as paragraph or header: 

cmark_node_type cmark_node_get_type(cmark_node *node); 

In Swift, it looks like this: 

func cmark_node_get_type(_ node: OpaquePointer!) -> cmark_node_type 

cmark_node_type is a C enum that has cases for the various block-level and inline 
elements that are defined in Markdown, as well as one case to signify errors: 

typedef enum { 

// Error status 
CMARK_NODE_NONE, 

//Block 

CMARK_NODE_DOCUIVIENT, 

CMARK_NODE_BLOCK_QUOTE, 


//Inline 

CMARK_NODE_TEXT, 

CMARK_NODE_EMPH, 

} cmark_node_type; 


Swift imports plain C enums as structs containing a single Ulnt32 property. Additionally, 
for every case in an enum, a global variable is generated: 

struct cmark_node_type : RawRepresentable, Equatable { 
public init(_ rawValue: Ulnt32) 
public init(rawValue; Ulnt32) 
public var rawValue: Ulnt32 

} 

var CMARK_NODE_NONE:cnnark_node_type {get} 
var CMARK_NODE_DOCUMENT: cmark_node_type {get} 


Only enums marked with the NS_ENUM macro, used by Apple in its 
Objective-C frameworks, are imported as native Swift enumerations. 
Additionally, library authors can annotate their enum cases with swift_name 
to make them member variables. 


In Swift, the type of a node should he a property of the Node data type, so we turn the 
cmark_node_get_type function into a computed property of our class: 

var type: cmark_node_type { 
return cmark_node_get_type(node) 

} 

Now we can just write node.type to get an element’s type. 

There are a couple more node properties we can access. For example, if a node is a list, it 
can have one of two list types: bulleted or ordered. All other nodes have the list type “no 
list.” Again, Swift represents the corresponding C enum as a struct, with a top-level 
variable for each case, and we can write a similar wrapper property. In this case, we also 
provide a setter, which will come in handy later in this chapter: 

var listType: cmark_list_type { 
get { return cmark_node_get_list_type(node)} 
set {cmark_node_set_list_type(node, newValue)} 

} 

There are similar functions for all the other node properties (such as header level, fenced 
code block info, and link URLs and titles). These properties often only make sense for 



specific types of nodes, and we can choose to provide an interface either with an 
optional (e.g. for the link URL) or with a default value (e.g. the default header level is 
zero). This illustrates a major weakness of the library’s C API that we can model much 
better in Swift. We’ll talk more about this below. 

Some nodes can also have children. For iterating over them, the CommonMark library 
provides the functions cmark_node_first_child and cmark_node_next. We want our 
Node class to provide an array of its children. To generate this array, we start with the 
first child and keep adding children until either cmark_node_first_child or 
cmark_node_next returns nil, signaling the end of the list. Note that this C null pointer 
automatically gets converted to an optional: 

var children: [Node] { 
var result: [Node] = [] 
varohild = omark_node_first_child(node) 
while let unwrapped = child { 
result.append(Node(node: unwrapped)) 
child = cmark_node_next(child) 

} 

return result 

} 

We could also have chosen to return a lazy sequence rather than an array (for example, 
by using sequence or AnySequence). However, there’s a problem with this: the node 
structure might change between creation and consumption of the sequence. In that 
case, the iterator for finding the next node would return wrong values, or even worse, 
crash. Depending on your use case, returning a lazily constructed sequence might be 
exactly what you want, but if your data structure can change, returning an array is a 
much safer choice. 

With this simple wrapper class for nodes, accessing the abstract syntax tree produced by 
the CommonMark library from Swift becomes a lot easier. Instead of having to call 
functions like cmark_node_get_list_type, we can just write node.listType and get 
autocompletlon and type safety. However, we aren’t done yet. Even though the Node 
class feels much more native than the C functions. Swift allows us to express a node in 
an even more natural and safer way, using enums with associated values. 


A Safer Interface 


As we mentioned above, there are many node properties that only apply in certain 
contexts. For example, it doesn’t make any sense to access the headerLevel of a list or the 
listType of a code block. Enumerations with associated values allow us to specify only 
the metadata that makes sense for each specific case. We’ll create one enum for all 
possible inline elements, and another one for block-level items. That way, we can 
enforce the structure of a CommonMark document. For example, a plain text element 
just stores a String, whereas emphasis nodes contain an array of other inline elements. 
These enumerations will be the public interface to our library, turning the Node class 
into an internal implementation detail: 

public enum Inline { 
case text(text: String) 
case softBreak 
case lineBreak 
case code(text: String) 
case html(text: String) 
case emphasis(children: [Inline]) 
case strong(children: [Inline]) 
case custom(literal: String) 

case link(children: [Inline], title: String?, url: String?) 
case image(children: [Inline], title: String?, url: String?) 

} 

Similarly, paragraphs and headers can only contain inline elements, whereas block 
quotations always contain other block-level elements. A list is defined as an array of list 
items, where each list item is represented by an array of Block elements: 

public enum Block { 
case list(items: [[Block]], type: ListType) 
case blockQuote(items: [Block]) 
case codeBlock(text: String, language: String?) 
case html(text: String) 
case paragraph(text: [Inline]) 
case heading(text: [Inline], level: Int) 
case custom(literal: String) 
case thematicBreak 

} 

The ListType is just a simple enum that states whether a list is ordered or unordered: 


public enum ListType { 
case unordered 
case ordered 

} 

Since enums are value types, this also lets us treat nodes as values by converting them to 
their enum representations. We follow the API Design Guidelines by using initializers 
for type conversions. We write two pairs of initializers: one pair creates Block and Inline 
values from the Node type, and another pair reconstructs a Node from these enums. This 
allows us to write functions that create or manipulate Inline or Block values and then 
later reconstruct a CommonMark document and use the C library to render it into HTML 
or back into Markdown text. 

Let’s start by writing an initializer that converts a Node into an Inline element. We switch 
on the node’s type and construct the corresponding Inline value. For example, for a text 
node, we take the node’s string contents, which we access through the literal property in 
the cmark library. We can safely force-unwrap literal because we know that text nodes 
always have this value, whereas other node types might return nil from literal. For 
example, emphasis and strong nodes only have child nodes and no literal value. To 
parse the latter, we map over the node’s children and call our initializer recursively. 
Instead of duplicating that code, we create an inline function, inlineChildren, that only 
gets called when needed. The default case should never get reached, so we choose to 
trap the program if it does. This follows the convention that returning an optional or 
using throws should generally only be used for expected errors, and not to signify 
programmer errors: 

extension Inline { 
init(_ node: Node) { 

let inlineChildren = { node.children.map(lnline.init)} 

switch node.type { 

case CMARK_NODE_TEXT: 

self = .text(text: node.literal!) 
case CMARK_NODE_SOFTBREAK: 

self = .softBreak 
case CMARK_NODE_LINEBREAK: 

self = .lineBreak 
case CMARK_NODE_CODE: 

self = .code(text; node.literal!) 
case CMARK_NODE_HTML_INLINE: 

self = .html(text: node.literal!) 
case CMARK_NODE_CUSTOIVI_INLINE: 



self = .custom(literal: node.literal!) 
case CMARK_NODE_EMPH: 

self = .emphasis(children: inlineChildrenQ) 
case CMARK_NODE_STRONG: 

self = .strong(children; inlineChildrenQ) 
case CMARK_NODE_LlNK: 

self = .link(children: inlineChildrenQ, title: node.title, url: node.urlString) 
case CMARK_NODE_lMAGE: 

self = .image(children: inlineChildrenQ, title: node.title, url: node.urlString) 

default: 

fatalErrorC'Unrecognized node:\(node.typeString)") 

} 

} 


Converting block-level elements follows the same pattern. Note that block-level 
elements can have either inline elements, list items, or other block-level elements as 
children, depending on the node type. In the cmark_node syntax tree, list items get 
wrapped with an extra node. In the listltem property on Node, we remove that layer and 
directly return an array of block-level elements: 

extension Block { 
init{_ node: Node) { 

let parselnlineChildren = { node.children.map(lnline.init)} 
let parseBlockChildren = { node.children.map(Block.init)} 
switch node.type { 
case CMARK_NODE_PARAGRAPH: 

self = .paragraph(text: parselnlineChildrenQ) 
case CMARK_NODE_BLOCK_QUOTE: 

self = .blockQuote(items: parseBlockChildrenQ) 
case CMARK_NODE_LiST: 
let type = node.listType == CMARK_BULLET_LiST? 

ListType.unordered : ListType.ordered 
self = .list(items: node.children.map {$0.listltem }, type: type) 
case CMARK_NODE_CODE_BLOCK: 

self = .codeBlock(text: node.literall, language: node.fencelnfo) 
case CMARK_NODE_HTML_BLOCK: 

self = .html(text: node.literall) 
case CMARK_NODE_CUSTOIVl_BLOCK: 

self = .custom(literal: node.literall) 
case CMARK_NODE_HEADING: 


self = .heading(text: parselnlineChildrenQ, level: node.headerLevel) 
case CMARK_NODE_THEMATIC_BREAK: 
self = .thematicBreak 

default: 

fatalErrorC'Unrecognized node:\(node.typeString)") 

} 

} 


Now, given a document-level Node, we can easily convert it into an array of Block 
elements. The Block elements are values: we can freely copy or change them without 
having to worry about references. This is very powerful for manipulating nodes. Since 
values, by definition, don’t care how they were created, we can also create a Markdown 
syntax tree in code, from scratch, without using the CommonMark library at all. The 
types are much clearer too; you can’t accidentally do things that wouldn’t make sense — 
such as accessing the title of a list — as the compiler won’t allow it. Aside from making 
your code safer, this is a very robust form of documentation — by just looking at the 
types, it’s obvious how a CommonMark document is structured. And unlike comments, 
the compiler will make sure that this form of documentation is never outdated. 

It’s now very easy to write functions that operate on our new data types. For example, if 
we want to build a list of all the level one and two headers from a Markdown document 
for a table of contents, we can just loop over all children and check whether they are 
headers and have the correct level: 

func tableOfContents(document: String) -> [Block] { 
let blocks = Node(markdown: document)?.children.map(Block.init) ?? [] 
return blocks.filter { 
switch $0 { 

case .headingL, let level) where level < 3: return true 
default: return false 

} 

} 


Before we build more operations like this, let’s tackle the inverse transformation: 
converting a Block back into a Node. We need this because we ultimately want to use the 
CommonMark library to generate HTML or other text formats from the Markdown 
syntax tree we’ve built or manipulated, and the library can only deal with 
cmark_node_type. 


Our plan is to add two initializers on Node: one that converts an Inline value to a node, 
and another that handles Block elements. We start by extending Node with a new 
initializer that creates a new cmark_node from scratch with the specified type and 
children. Recall that we wrote a deinit, which frees the root node of the tree (and 
recursively, all its children). This deinit will make sure that the node we allocate here 
gets freed eventually: 

extension Node { 

convenience init(type: cmark_node_type, children: [Node] = []) { 
self.init(node: cmark_node_new(type)) 
for child in children { 

cmark_node_append_child(node, chi id. node) 

} 

} 


We’ll frequently need to create text-only nodes, or nodes with a number of children, so 
let’s add three convenience initializers to make that easier: 

extension Node { 

convenience init(type: cmark_node_type, literal: String) { 
self.init(type: type) 
self.literal = literal 

} 

convenience init(type: cmark_node_type, blocks: [Block]) { 
self.init(type: type, children: blocks.map(Node.init)) 

} 

convenience init(type: cmark_node_type, elements: [Inline]) { 
self.init(type: type, children: elements.map(Node.init)) 

} 

} 

Now we’re ready to write the two conversion initializers. Using the initializers we just 
defined, it becomes very straightforward: we switch on the element and create a node 
with the correct type. Here’s the version for inline elements: 

extension Node { 

convenience init(element: Inline) { 
switch element { 
case .text(let text): 

self.init(type: CMARK_NODE_TEXT, literal: text) 


case .emphasis(let children): 

self.init(type: CIVIARK_NODE_EMPH, elements: children) 
case .code(lettext): 

self.init(type: CMARK_NODE_CODE, literal: text) 
case .strong(let children): 

self.init(type: CIVIARK_NODE_STRONG, elements: children) 
case .html(let text): 

self.init(type:CIVIARK_NODE_HTML_INLINE, literal: text) 
case .custom(let literal): 

self.init(type: C[VIARK_NODE_CUSTOM_INLINE, literal: literal) 
case let .link(children, title, url): 
self.init(type: CMARK_NODE_LINK, elements: children) 
self .title = title 
self.urlString = url 
case let .image(children, title, url): 
self.init(type: C[VIARK_NODE_IMAGE, elements: children) 
self .title = title 
urlString = url 
case .softBreak: 

self.init(type:CIVIARK_NODE_SOFTBREAK) 
case .lineBreak: 

self.init(type:CIVIARK_NODE_LINEBREAK) 

} 

} 

} 

Creating a node from a block-level element is very similar. The only slightly more 
complicated case is lists. Recall that in the above conversion from Node to Block, we 
removed the extra node the CommonMark library uses to represent lists, so we need to 
add that back in here: 

extension Node { 
convenience init(block: Block) { 
switch block { 

case .paragraph(let children): 

self.init(type: C[VIARK_NODE_PARAGRAPH, elements: children) 
case let .list(items, type): 

let listitems = items.map { Node(type: CMARK_NODE_ITEM, blocks: $0)} 
self.init(type: C[VIARK_NODE_LIST, children: listitems) 
listType = type == .unordered 
?CMARK_BULLET_LIST 


:CMARK_ORDERED_LIST 
case .blockQuote(let items): 

self.init(type: CMARK_NODE_BLOCK_QUOTE, blocks: items) 
case let .codeBlock(text, language): 
self.init(type: CIVlARK_NODE_CODE_BLOCK, literal: text) 
fencelnfo = language 
case .html(let text): 

self.init(type:CMARK_NODE_HTML_BLOCK, literal: text) 
case .custom(let literal): 

self.init(type: C[VlARK_NODE_CUSTOM_BLOCK, literal: literal) 
case let .heading(text, level): 
self.init(type: CIVlARK_NODE_HEADlNG, elements: text) 
headerLevel = level 
case .thematicBreak: 

self.init(type:CMARK_NODE_THEMATlC_BREAK) 

} 

} 

} 

Finally, to provide a nice interface for the user, we define a public initializer that takes 
an array of block-level elements and produces a document node, which we can then 
render into one of the different output formats: 

extension Node { 

public convenience initfblocks: [Block]) { 
self.initftype: CMARK_NODE_DOCUMENT, blocks: blocks) 

} 

} 

Now we can go in both directions: we can load a document, convert it into [Block] 
elements, modify those elements, and turn them back into a Node. This allows us to 
write programs that extract information from Markdown or even change the Markdown 
dynamically. By first creating a thin wrapper around the C library (the Node class), we 
abstracted the conversion from the underlying C API. This allowed us to focus on 
providing an interface that feels like idiomatic Swift. The entire project is available on 
GitHub. 




An Overview of Low-Level Types 

There are many types in the standard library that provide low-level access to memory. 
Their sheer number can be overwhelming, as can daunting names like 
UnsafeMutableRawBufferPointer. The good news is that they’re named consistently, so 
each type’s purpose can be deduced from its name. Here are the most important naming 
parts: 

-> A managed type has automatic memory management. The compiler will 
allocate, initialize, and free the memory for you. 

-> An unsafe type doesn’t provide automated memory management (as opposed to 
managed). You have to allocate, initialize, deallocate, and deinitialize the 
memory explicitly. 

-> A buffer type works on multiple (contiguously stored) elements rather than a 
single element and provides a Collection interface. 

-> A pointer type has pointer semantics (just like a C pointer). 

-> A raw type contains untyped data. It’s the equivalent of a void* in C. Types that 
don’t contain raw in their name have typed data. 

-> A mutable type allows the mutation of the memory it points to. 

If you want raw storage but don’t need to interact with C, you can use the ManagedBuffer 
class to allocate the memory. This Is what Swift’s collections use under the hood to 
manage their memory. It consists of a single header value (for storing data such as the 
number of elements) and contiguous memory for the elements. It also has a capacity 
property, which isn’t the same as the number of actual elements: for example, an Array 
with a cou nt of 17 might own a buffer with a capacity of 32, meaning that 15 more 
elements can he added before the Array has to allocate more memory. There’s also a 
variant called ManagedBufferPointer, but it doesn’t have many applications outside the 
standard library and may be removed in the future. 

Sometimes you need to do manual memory management. For example, you might want 
to pass a Swift object to a C function with the goal of retrieving it later. C APIs that use 
callbacks (function pointers) often take an additional context argument (usually an 
untyped pointer, or void*) that they pass on to each invocation of the callback In order to 
work around C’s lack of closures. When you call such a function from Swift, it’d be 
convenient to be able to pass a native Swift object as the context value. However, C 
doesn’t know about Swift’s memory management. If the API is synchronous, you can 
just pass in the Swift object and convert it back from the untyped pointer when you 



receive it in the callback, and all will be fine (we’ll look at this in detail in the next 
section). However, if the API is asynchronous, you have to manually retain and release 
that object, because otherwise the Swift runtime may deallocate it once it goes out of 
scope. In order to do that, there’s the Unmanaged type. It has methods for retain and 
release, as well as initializers that either modify or keep the current retain count. 


Pointers 

In addition to the OpaquePointerType we’ve already seen. Swift has eight more pointer 
types that map to different classes of C pointers. 

The base type, UnsafePointer, is similar to a const pointer in C. It’s generic over the data 
type of the memory it points to, so UnsafePointer<lnt> corresponds to const int*. 

Notice that C makes a difference between const int* (a mutable pointer to immutable 
data, i.e. you can’t write to the pointed data using this pointer) and int* const (an 
immutable pointer, i.e. you can’t change where this pointer points to). UnsafePointer in 
Swift is equivalent to the former variant. As always, you control the mutability of the 
pointer itself by declaring the variable with var or let. 

You can create an unsafe pointer from one of the other pointer types using an initializer. 
Swift also supports a special syntax for calling functions that take unsafe pointers. You 
can pass any mutable variable of the correct type to such a function by prefixing it with 
an ampersand, thereby making it an in-out expression: 

var X = 5 

func fetch(p: UnsafePointer<lnt>) -> Int { 
return p.pointee 

} 

fetch(p: Sex)//5 

This looks exactly like the incut parameters we covered in the functions chapter, and it 
works in a similar manner — although in this case, nothing is passed back to the caller 
via this value because the pointer isn’t mutable. The pointer that Swift creates behind 
the scenes and passes to the function is guaranteed to be valid only for the duration of 
the function call. Don’t try to return the pointer from the function and access it after the 
function has returned — the result is undefined. 


There’s also a mutable variant, named UnsafeMutablePointer. This struct works just like 
a regular C pointer; you can dereference the pointer and change the value of the 
memory, which then gets passed back to the caller via the in-out expression: 

func increment(p: UnsafeMutablePointer<lnt>) { 
p.pointee -t= 1 

} 

var y = 0 
increment(p: &y) 
y//7 

Rather than using an in-out expression, you can also allocate memory directly using 
UnsafeMutablePointer. The rules for allocating memory in Swift are similar to the rules 
in C: after allocating the memory, you hrst need to initialize it before you can use it. 
Once you’re done with the pointer, you need to deallocate the memory: 

//Allocate and initialize memory for two Ints 

letz = UnsafeMutablePointer<lnt>.aUocate(capacity: 2) 

z.initialize(to: 42, count: 2) 

z.pointee //42 

// Pointer arithmetic: 

(z-tl).pointee = 43 

//Subscripts: 

z[1]//43 

//Deallocate the memory 

//If Pointee is a nan-trivial type (e.g. a class), you must 
//call deinitialize before calling deallocate. 
z.deallocate(capacity: 2) 

//Don't access pointee after deallocate 

We saw another example of this in the chapter on strings when we allocated a pointer to 
an NSRange for the purpose of receiving a value back from a Foundation API. 

In C APIs, it’s also very common to have a pointer to a sequence of bytes with no specific 
element type (void* or const void*). The equivalent counterparts in Swift are the 
UnsafeMutableRawPointer and UnsafeRawPointer types. C APIs that use void* or 
const void* get imported as these types. Unless you really need to operate on raw bytes, 
you’d usually directly convert these types into UnsafejMutable] Pointer or other typed 
variants by using one of their instance methods (such as assumingMemoryBound(to:), 
bindMemory(to:), or load(fromByteOffset:as:)). 


Unlike C, Swift uses optlonals to distinguish between nullable and non-nullable pointers. 
Only values with an optional pointer type can represent a null pointer. Under the hood, 
the memory layout of an UnsafePointer<T> and an Optional<UnsafePointer<T» is exactly 
identical; the compiler is smart enough to map the .none case to the all-zeros bit pattern 
of the null pointer. 

Sometimes a C API has an opaque pointer type. For example, in the cmark library, we 
saw that the type cmark_node* gets imported as an OpaquePointer. The definition of 
cmark_node isn’t exposed in the header, and therefore, we can’t access the pointee’s 
memory. You can convert opaque pointers to other pointers using an Initializer. 

In Swift, we usually use the Array type to store a sequence of values contiguously. In C, 
an array is often returned as a pointer to the first element and an element count. If we 
want to use such a sequence as a collection, we could turn the sequence into an Array, 
but that makes a copy of the elements. This is often a good thing (because once they’re 
in an array, the elements are memory managed by the Swift runtime). However, 
sometimes you don’t want to make copies of each element. For those cases, there are the 
Unsafe[Mutable]BufferPointer types. You initialize them with a pointer to the start 
element and a count. From then on, you have a (mutable) random-access collection. The 
buffer pointers make it a lot easier to work with C collections. 

Finally, the Unsafe[Mutable]RawBufferPointer types make it easier to work with raw 
memory as collections (they provide the low-level equivalent to Data and NSData). 


While pointers require you to manually allocate and free memory, they do 
perform the standard ARC memory management operations on the elements 
you store through a pointer. When you have an unsafe mutable (buffer) pointer 
whose Pointee type is a class type, it’ll retain every object you store with 
initialize and release it again when you call deinitialize. 


Function Pointers 


Let’s look at a concrete example of a C API that uses pointers. Our goal is to write a Swift 
wrapper for the qsort sorting function in the C standard library. The type as it’s 
imported in Swift’s Darwin module (or if you’re on Linux, Glibc) is given below: 

public func qsort( 

_ base: UnsafeMutableRawPointerl, 

_ nel: int, 



_ width: Int, 

_ compar: ©escaping @convention(c) (UnsafeRawPointer?, 

UnsafeRawPointer?) 

-> Int32) 

The man page (man qsort) describes how to use the qsort function: 


The qsortO and heapsortO functions sort an array of nel objects, the initial 
member of which is pointed to by base. The size of each object is specihed by 
width. 

The contents of the array base are sorted in ascending order according to a 
comparison function pointed to by compar, which requires two arguments 
pointing to the objects being compared. 


And here’s a wrapper function that uses qsort to sort an array of Swift strings: 

func qsortStrings(array: inout [String]) { 
qsort(&array, array.count, MemoryLayout<String>.stride) {a, b in 
let I = a!.assuming[VlemoryBound(to: String.self).pointee 
let r = b!.assumingMemoryBound(to: String.self).pointee 
if r > I { return -1 } 
else if r = = I { return 0 } 
else { return 1} 

} 

} 

Let’s look at each of the arguments being passed to qsort: 

-> The first argument is a pointer to the base of the array. Swift arrays automatically 
convert to C-style base pointers when you pass them into a function that takes an 
UnsafePointer. We have to use the & prehx because it’s an 
UnsafeMutableRawPointer (avoid *base in the C declaration). If the function 
didn’t need to mutate its input and were declared in C as const void *base, the 
ampersand wouldn’t be needed. This matches the difference with inout 
arguments in Swift functions. 

-> Second, we have to provide the number of elements. This one is easy; we can use 
the count property of the array. 



-> Third, to get the width of each eiement, we use MemoryLayout.stride, not 
MemoryLayout.size. In Swift, MemoryLayout.size returns the true size of a type, 
but when locating elements in memory, platform alignment rules may lead to 
gaps between adjacent elements. The stride is the size of the type, plus some 
padding (which may be zero) to account for this gap. For strings, size and stride 
are currently the same on Apple’s platforms, but this won’t be the case for all 
types — for example, MemoryLayout<(lnt32, Bool)>.size is 5 and 
MemoryLayout<(lnt32, Bool)>.stride is 8. When translating code from C to Swift, 
you probably want to write MemoryLayout.stride in cases where you would’ve 
usedsizeof inC. 

-> The last parameter is a pointer to a C function that’s used to compare two 

elements from the array. Swift automatically bridges a Swift function type to a C 
function pointer, so we can pass any function that has a matching signature. 
However, there’s one big caveat: C function pointers are just pointers; they can’t 
capture any values. For that reason, the compiler will only allow you to provide 
functions that don’t capture any external state (for example, no local variables 
and no generics). It signifies this with the @convention(c) attribute. 

The compar function accepts two raw pointers. Such an UnsafeRawPointer can be a 
pointer to anything. The reason we have to deal with UnsafeRawPointer (and not 
UnsafePointer<String>) is because C doesn’t have generics. However, we know that we 
get passed in a String, so we can interpret it as a pointer to a String. We also know the 
pointers are never nil here, so we can safely force-unwrap them. Finally, the function 
needs to return an Int32: a positive number if the first element is greater than the 
second, zero if they’re equal, and a negative number if the first is less than the second. 


Making It Generic 

It’s easy enough to create another wrapper that works for a different type of elements; we 
can copy and paste the code and change String to a different type and we’re done. But we 
should really make the code generic. This is where we hit the limit of C function 
pointers. The code below fails to compile because it captures things from outside the 
closure. More specifically, it captures the comparison and equality operators, which are 
different for each generic parameter. There’s nothing we can do about this — we simply 
encountered an inherent limitation of C: 

extension Array where Element: Comparable { 
mutatingfunc quicksortO { 

// Error: a C function pointer cannot be formed 
// from a closure that captures generic parameters 


qsort(&self, self.count, MemoryLayout<Element>.stride) {a, b in 
let I = a!.assumingMemoryBound(to: Element. self). pointee 
let r = b!.assumingMemoryBound(to: Element. self). pointee 
if r > I { return -1} 
else if r == I { return 0} 
else { return 1} 

} 

} 

} 


One way to think about this iimitation is by thinking like the compiler. A C 
function pointer is just an address in memory that points to a block of code. 
For functions that don’t have any context, this address will be static and 
known at compile time. However, in case of a generic function, an extra 
parameter (the generic type) is passed in. Therefore, there are no addresses 
for specialized generic functions. This is the same for closures. Even if the 
compiler could rewrite a closure in such a way that it’d be possible to pass it as 
a function pointer, the memory management couldn’t be done automatically 
— there’s no way to know when to release the closure. 


In practice, this is a problem for many C programmers as well. On macOS, there’s a 
variant of qsort called qsort_b, which takes a block — a closure — instead of a function 
pointer as the last parameter. If we replace qsort with qsort_b in the code above, it’ll 
compile and run fine. 

However, qsort_b isn’t available on most platforms since blocks aren’t part of the C 
s tandard . And other functions aside from qsort might not have a block-based variant 
either. Most C APIs that work with callbacks offer a different solution. They take an extra 
UnsafeRawPointer as a parameter and pass that pointer on to the callback function. The 
user of the API can then use this to pass an arbitrary piece of data to each invocation of 
the callback function, qsort also has a variant, qsort_r, which does exactly this. Its type 
signature includes an extra parameter, thunk, which is an UnsafeRawPointer. Note that 
this parameter has also been added to the type of the comparison function pointer 
because qsort_r passes the value to that function on every invocation: 

public func qsort_r( 

_base: UnsafeMutableRawPointer!, 

_nel: Int, 

_width: Int, 





_thunk: UnsafeMutableRawPointer!, 

_compar: ©escaping @convention(c) 

(UnsafeMutableRawPointer?, UnsafeRawPointer?, UnsafeRawPointer?) 
-> Int32 


If qsort_b isn’t available on our platform, we can reconstruct it in Swift using qsort_r. We 
can pass anything we want as the thunk parameter, as long as we cast it to an 
UnsafeRawPointer. In our case, we want to pass the comparison closure. We can 
automatically create an UnsafeRawPointer out of a variable defined with var by using an 
in-out expression. So all we need to do is store the comparison closure that’s passed as 
an argument to our qsort_b variant in a variable named thunk. Then we can pass the 
reference to the thunk variable into qsort_r. Inside the callback, we cast the void pointer 
back to its real type. Block, and then simply call the closure: 

typealias Block = (UnsafeRawPointer?, UnsafeRawPointer?) -> Int32 
func qsort_block(_ array: UnsafeMutableRawPointer, _ count: Int, 

_ width: Int, f: ©escaping Block) 

{ 

var thunk = f 

qsort_r(array, count, width, &thunk) {(ctx, pi, p2) -> Int32 in 
let comp = ctx!.assumingMemoryBound(to: Block. self). pointee 
return comp(p1, p2) 

} 

} 

Using qsort_block, we can redefine our qsortWrapper function and provide a nice 
generic interface to the qsort algorithm that’s in the C standard library: 

extension Array where Element: Comparable { 
mutating func quicksortO { 

qsort_block(&self, self.count, MemoryLayout<Element>.stride) {a, b in 
let I = a!.assumingMemoryBound(to: Element. self). pointee 
let r = b!.assumingMemoryBound(to: Element. self). pointee 
if r > I { return -1} 
else if r == I { return 0} 
else { return 1} 

} 

} 


varx = [3,1,2] 

x.quicksortQ 

x//[l,2,3] 

It might seem like a lot of work to use a sorting algorithm from the C standard library. 
After all. Swift’s built-in sort function is much easier to use, and it’s faster in most cases. 
However, there are many other interesting C APIs out there that we can wrap with a 
type-safe and generic interface using the same technique. 


Recap 

Rewriting an existing C library from scratch in Swift is certainly fun, but it may not be 
the best use of your time (unless you’re doing it for learning, which is totally awesome). 
There’s a lot of well-tested C code out there, and throwing it all out would be a huge 
waste. Swift is great at interfacing with C code, so why not make use of it? Having said 
that, there’s no denying that most C APIs feel very foreign in Swift. Moreover, it’s 
probably not a good idea to spread C constructs like pointers and manual memory 
management across your entire code base. 

Writing a small wrapper that handles the unsafe parts internally and exposes an 
idiomatic Swift interface — as we did in this chapter for the Markdown library — gives 
you the best of both worlds: you don’t have to reinvent the wheel (i.e. write a complete 
Markdown parser) and yet it feels 100 percent native to developers using the API. 


Final Words 




We hope you enjoyed this journey through Swift with us. 


Despite its young age, Swift is aiready a compiex ianguage. It’d be a daunting task to 
cover every aspect of it in one book, iet alone expect readers to remember it all. 

We chose the topics for this book largely based on our own interests. What did we want 
to know that was missing from the official documentation? How do things work under 
the hood? And perhaps even more importantly, why does Swift behave the way it does? 

Even if you don’t Immediately put everything you learned to practical use, we’re 
confident that having a better understanding of your language makes you a more 
accomplished programmer. 

Swift is still changing rapidly. While the era of large-scale source-breaking changes is 
probably behind us, there are several areas where we expect major enhancements in the 
coming years: 

-> The big goal for Swift 5 is achieving ABI stability (application binary interface). 
This mostly affects internal details like memory layouts and calling conventions, 
but one prerequisite for AB7 stability that affects everyone is finalizing the 
standard library APT This is why enhancements to the generics system that the 
standard library can profit from are a major focus for Swift 5. 

-> An explicit memory ownership model will allow developers to annotate 
function arguments with ownership requirements. The goal is to give the 
compiler all the information it needs to avoid unnecessary copies when passing 
values to functions. We’re already seeing the first pieces of this in Swift 4 with the 
introduction of compiler-enforced exclusive memory access. 

-> Discussions about adding flrst-class concurrency support to Swift are still in 
their infancy, and this is a project that will take several years to complete. Still, 
there’s a good chance we’ll get something like the coroutine-based async/await 
model that’s popular in other languages in the not-too-distant future. 

If you’re interested in shaping how these and other features turn out, remember that 
Swift is being developed in the open. Consider joining the swift-evolution mailing list 
and adding your perspective to the discussions. 

Finally, we’d like to encourage you to take advantage of the fact that Swift is open source. 
When you have a question the documentation doesn’t answer, the source code can often 
give you the answer. If you made it this far, you’ll have no problem finding your way 






through the standard library source flies . Being able to check how things are 
implemented in there was a big help for us when writing this book. 



